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To Our Customers 

This is a reference manual, and its organization reflects the relationship between 
TRSDOS and DISK BASIC. TRSDOS is the fundamental software, so it's described 
first. DISK BASIC is a language supported by TRSDOS, so it's described after 
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General Information 



Introduction 



This book is a combined operation and reference manual for the 
TRS-80 Disk Operating System. It will tell you how to operate the 
hardware and how to use the software. 

For many of you, there will be more than enough information. ("All 
I want to do is use the Computer, not understand it!") Don't worry, 
this book is designed so that you can start programming in DISK 
BASIC (if that's what you want to do) right away. All you have to do 
is read the chapter on Mini Disk Operation . . . skim through TRSDOS 
Overview and TRSDOS Commands ... and on to DISK BASIC. 

But DISK BASIC is just one aspect of TRSDOS. It's not a 
part of TRSDOS, but a program that TRSDOS executes. Using 
DISK BASIC without any awareness of the capabilities of TRSDOS 
is rather like riding in a Pullman car without any knowledge of the 
engine, freight cars, diner and other parts of a train. It's true that 
TRSDOS will do all that's necessary to let you ride comfortably along 
in BASIC; but eventually you're going to want to have a say in where 
the train goes, what its schedule is, and what goes in all those freight 
cars. That's when you need to understand TRSDOS. 

The illustration below shows the relationship between the Computer, 
Expansion Interface and Mini Disk Drives. 




The first drive(Drive 0) always contains the TRSDOS 
diskette, which is pre-recorded with the Operating System 
software: an executive program, and several auxiliary 
programs, including DISK BASIC. The executive program 
is loaded into the first 4K bytes of RAM, and stays there 
while TRSDOS is in control. The auxiliary programs 
are loaded as needed. 



Second, third and fourth drives can contain 
diskettes, for storing your programs and data. 

The Expansion Interface contains the real- 
time clock, disk controller IC, and optional 
extra RAM (addresses above 32767). 

The Keyboard/Computer contains a built-in (ROM) 
program which takes over at power-up, and loads 
the TRSDOS executive program from the system 
diskette (in Drive 0). If the Mini Disk equipment is 
not connected, this ROM program can transfer control 
to LEVEL II BASIC. 
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One section of this book you should definitely become familiar with 
is the Glossary. We've tried to give definitions for all the "computer 
words" and everyday words with special meanings in this book. Even 
if you've heard all the terms, you'll gain some useful information 
from the Glossary, because it's customized for the TRS-80. 

First you make a BACKUP . . . 

You received one TRSDOS diskette with your Mini Disk drive 26-1 160. 
This diskette contains the operating system software. Without this 
disk, you haven't got a disk operating system. 

So, your first disk operation . . . before you remove the write protect 
tape from the TRSDOS diskette . . . should be to duplicate TRSDOS 
onto a blank diskette. You'll find abbreviated instructions for making 
a duplicate (BACKUP) of your TRSDOS diskette at the end of the 
Mini Disk Operation chapter. 



Notation Conventions 

In descriptions of syntax for commands, statements and dialog with 
the Computer, we'll use the following conventions for clarity and 
brevity. 

p 1 This special symbol represents a mandatory 

blank space. Unless it is specified, any 
blanks that appear in the syntax are optional. 
Example: 
DIR#:1 
The blank space is required after the R. 



< space > 



"Press the HJhH;l key." 
"Press the space-bar." 



CAPITALS and 

punctuation 



Indicate material which must be entered 

exactly as it appears. The only punctuation 

symbols not entered are the special cases 

(brackets and triple-period . . .) explained 

below. 

Example: 

LOAD"filespec" 

Only the command LOAD and the quote 

marks are entered verbatim; you supply 

the filespec. 
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Notation, continued 

SCREENED CAPITALS Represent input you supply, upon prompt- 
ing from the Computer. This convention 
will only be used where necessary to 
distinguish between Computer prompting 
and user input. 
Example: 

HOW MflNV FILES? 5 l=MHd;l 

The Computer asks the question, and you 
answer it. 

lowercase italics Represent words, letters or values you 

supply from a set of acceptable values for 

that situation. 

Example: 

var = exp 

A variable name goes on the left, and an 

expression goes on the right. 

[ ] Brackets enclose optional material. 

Example: 
CLOSE [filenum ] 

filenum (the file number) is optional after 
CLOSE. The brackets are not actually 
typed in. 

The triple-period symbol inside brackets 
indicates that preceding items in the 
brackets may be repeated. 
Example: 

INPUT ["prompting message";] var[,var . . .] 
The INPUT variable-list may include 
more than one variable. The periods are 
not actually typed in. 

var([, ....]) Signifies an array. If no commas are 

placed inside the parentheses, a 
one-dimensional array is intended; 
1 comma indicates a two-dimensional 
string array; etc. 
Examples: 

A$( , ) indicates a two-dimensional 
string array. 

Bl( ) indicates a single-dimensioned 
array. 
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Notation, continued 



exp 



var 



nmexp 

nmvar 
exp$ 

var$ 

con 

nmcon 

con$ 

numerical 
suffixes 



String or numerical expression 

String or numerical variable name 

Numerical expression, including constants, 
variables, functions 

Numerical variable name 

String expression, including constants in 
quotes, variables, functions and operators 

String variable name 

Constant, either string or numerical 

Numerical constant 

String constant 

Attached to distinguish between different 

arguments and parameters of the same type. 

Example: 

COFYtyfilespecl fIO\j>filespec2 
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Versions and Releases 

Some of you may be a little confused about the terminology, 
"Version X.Y". The "X" and "Y" will change as TRSDOS is 
updated, so here's an explanation. 

A new version represents a substantial expansion of the previous 
version. For example, new utilities, high-level languages, etc., might 
be included in a new version. Such versions are numbered by the 
integers 1, 2, 3, — 

A new release, on the other hand, is simply an update of the previous 
release of a given version. This later release generally includes wider 
implementations and enhancements of commands and fixes for any 
problems in the earlier release. The releases are numbered by 
decimal fractions, .1, .2, .3, ... . 

Therefore, when we refer to Version 2.1, that's short for the first 
Release of Version 2. 

Note: In its original printing, this Manual describes TRSDOS 
Version 2. 1 , and DISK BASIC Version 1.1. The Manual will be 
updated as required by later versions and releases. 
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Mini Disk Operation 



Introduction 



The TRS-80 Mini Disk drive is a mass storage device custom 
manufactured for use with the TRS-80 Microcomputer. It combines 
the compactness of a cassette recorder with the high-speed, reliable 
data access of the larger disk drive units. Information is magnetically 
recorded on and read from flexible ("floppy") diskettes. 

In simplified terms, the Mini Disk consists of a magnetic read/write 
head, similar to that on a tape recorder; a stepper motor to move the 
head across the diskette surface; a drive motor and hub assembly to 
rotate the diskette; and the necessary logic circuitry to control 
the read/write process and the motor speed. See Figures 1 and 2. 



There are two types of drives, 
distinguished by their Radio 
Shack Catalog Numbers, 
26-1 160 and 26-1 161. Your 
disk system must include one 
(and only one) 26-1 160 and 
may include up to three 
26-1 161 drives. 

Included with 26-1160 

Drive unit: Incorporates 
special terminating resistors 
not present in the 26-1 161 
units. 



Interconnect cable: For con- 
nection of 26-1 160 and up to 
three optional 26-1 161 drives 
to the Expansion Interface. 

1 TRSDOS diskette: Contains 
the operating system software, 
utilities, DISK BASIC, etc. 

Included with each 26-1 161 

Drive unit: Does not incorpo- 
rate terminating resistors. 

Blank diskette: Can be 
formatted or backed up for 
use with TRSDOS. 




\i 



Figure 1. Mini Disk Drive. 



MAGNETIC READ/WRITE HEAD 



DISKCONTROLLE 




Figure 2. Functional components in a Mini Disk drive. 
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Connections 



The power to all components in the TRS-80 system should be "off 
while you make connections. 

Look at the ribbon-type connector cable included with your 26-1 160 
Mini Disk drive. Notice that the cable has four edge card connectors 
through its length, and a single connector at the other end. Connect 
the single plug to the edge-card jack on the left rear of the 
Expansion Interface, as shown in Figure 3. Be sure the plug is 
oriented so the cable exits from the bottom. 

Before connecting the Drive(s) to the cable, note the following rules: 

1) 26-1 160 must always be the "terminal" or final drive on the 
cable; that is, of all your drives, it must always be the farthest 
away from the Expansion Interface. This is because it includes 
the terminating resistors mentioned above. 

2) The connector closest to the Expansion Interface must always 
be plugged in to a drive. The other connectors can be 
"empty". 



- LEFT REAR OF EXPANSION INTERFACE 
(MINI-DISK CONNECTION) 




CABLE MUST EXIT AT BOTTOM 
FOR PROPER CONNECTION 



RIBBON TYPE CONNECTOR CABLE 



Figure 3. Connecting the ribbon cable to the Expansion Interface. 
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Connect each Mini Disk 
unit to the cable, taking 
care to orient the plug 
properly as shown in 
Figure 4. Inside each 
plug is a small plastic 
connector. If the plug 
doesn't mate properly, 
check to see that the 
plug is oriented so the 
pin lines up with the 
slot. 




EDGE CARD PLUGS 



GUIDE SLOT" 



Figure 4. Connecting the cable to the Mini Disk. 



Examples: 



If you have just one drive (must be 26-1 160), then connect it to the 
first connector plug, so as not to leave any empty connectors between 
the Drive and the Expansion Interface. Leave the last three connectors 
empty. 

If you have two drives, then connect 26-1 161 to the first connector 
and 26-1 160 to the second connector. Leave the last two connectors 
empty. 

Figure 5 shows a Mini Disk system with four drives connected. 

Connect each Mini Disk to a source of 120 VAC, using the power cord 
provided. 



IilflU 
? i " 'mm P i JB | lZJHI 

26-1160 26-1161 26-1161 26-1161 



Figure 5. A complete four-drive Mini Disk System. 




■- — 
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Drive Numbering 

TRSDOS requires at least one Mini Disk drive, and can handle up to 
four. Under TRSDOS, these drives are referred to as drives 0,1,2 and 3 
(where drive is closest to the Expansion Interface, and drive 3 is 
farthest away). See Figure 5. These designations cannot be changed — 
they are built into the ribbon cable connector. 

When the Computer attempts a bootstrap operation (power-on or 
reset), it will automatically attempt to load TRSDOS from drive 0. 
Therefore a TRSDOS diskette must be in drive when you power on 
or reset the Computer. In fact, the TRSDOS diskette should always 
remain in drive while TRSDOS is in use, except in special cases. 



Operation 



Before powering on the disk system, you need to understand a few 
things about how the drives work. 

The disk drive does not rotate continuously while it is "on". It only 
rotates when a Motor-On signal is sent from the Computer. If more 
than one Mini Disks are connected, the Motor-On signal will turn them 
all on and off simultaneously, even if only one of them is to be 
accessed by the Computer. This signal is sent about a second before 
the Computer accesses the disk, to allow the drives to reach operating 
speed. 

While the Computer is accessing one of the Mini Disks, the red light 
(LED) on the front of that Mini Disk will remain lit. 

Caution: Do not open a drive latch to insert or remove a diskette 
while the drive motors are running (i.e., while one of the LEDS 
is lit). 



How a Diskette Works 

A diskette is simply a circular plastic sheet, one side of which is 
coated with a highly polished layer of ferromagnetic material. Similar 
to a 45 RPM record, the diskette has a large spindle hole to 
accommodate the drive hub, and a small hole which indexes the 
diskette as it rotates. 
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A blank diskette (either brand-new or magnetically erased) contains 
no information. TRSDOS has a special utility program (called 
FORMAT) which takes a blank diskette and organizes it into 
concentric "tracks" and subtracks called "sectors". See Figure 6. 
These divisions are like the numbered pages in a book. (FORMAT 
also places a small amount of system and bookkeeping information 
onto each diskette. For more information, see Extended Utilities, 
FORMAT.) 



TRACK 1, SECTOR 8 
DATA 256 BYTES 




TRACK/SECTOR ID FOR 
TRACK 1, SECTOR 8 



TRACKS 1,2 35 



DIRECTION OF ROTATION 



Figure 6. Track/sector organization on a formatted diskette. 



Each diskette is permanently sealed inside its jacket to prevent 
bending, creasing, scratching or contamination of the diskette 
surface. When the diskette is loaded into the drive, a hub assembly 
grips the diskette; when the drive motor is on, the diskette 
rotates inside its jacket. The specially treated jacket lining cleans 
the diskette as it rotates. 

Notice that the TRSDOS diskette comes with a piece of tape across 
the top (above the label). This tape covers the diskette's write 
protect notch. With the notch covered, the diskette is physically 
protected from being written to. (A "write operation" is any 
alteration of the data stored on the diskette. In contrast, a "read" 
does not alter the information — merely accesses it.) 
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Remove the tape from the diskette if you intend to write to it; and 
place a tape over the notch on any diskette you don't want to 
accidentally write to. 



See Figure 7. 



WRITE PROTECT NOTCH 



READ/WRITE NOTCH 




WRITE PROTECT TAB 



SECTOR HOLE 







. s 



Figure 7. A diskette; a write-protected diskette; a diskette in 
protective storage envelope. 



Inserting a Diskette 

1 . Be sure the Mini Disk drive is stopped when you insert or 
remove a diskette. 

2. Open the front of the Mini Disk drive. Gently insert the diskette 
into the vertical slot, with the write protect notch up and the 
diskette label to the right (Figure 8). Be sure not to close the 
latch until the diskette is inserted all the way and seated 
properly, or you may damage it. 

3. Close the Mini Disk latch. This causes the spindle-hub assembly 
to grip the diskette. If the door doesn't close easily, don't 
force it. Re-insert the diskette and try again. 







Figure 8. Inserting a diskette. 
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Power-Up Sequence 



You should always power up the peripherals (disk drives, printer, 
Expansion Interface, etc.) first, and the TRS-80 CPU/keyboard last. 
Also note that turning the peripherals on and off while the Computer 
is on may confuse the system and cause abnormal operation. Work 
done on a currently open file may be lost. 

The power switch for each Mini Disk is on the rear of the unit. Power 
is "on" when the toggle switch is in the up position, and "off when 
the switch is down. 

1 . Turn on the Expansion Interface. 

2. Turn on the Mini Disk drives: first the terminal drive, 26-1 160, 
then the other drives, if any. 

3. When you turn on the TRS-80 CPU/keyboard, the Computer 
will instantly attempt to load TRSDOS from Drive 0. So before 
turning on the CPU, carefully insert the TRSDOS diskette into 
drive as explained above under "Inserting a Diskette". You 
may also want to insert formatted diskettes into the other drives 
now; however, these may be inserted any time the drives are 
stopped. 

Another approach would be to plug all devices into an adequate 
power strip and turn them all on with a single switch. 



Care of Diskettes 

Diskettes are precision recording media. Handle them very carefully 
to get maximum life from each diskette. In general, follow the special 
handling precautions used with both tape cassettes and high fidelity 
records. 

1. Keep the diskette in its storage envelope whenever it is not in 
one of the drives. Don't leave the diskettes in the drives 
needlessly, for example, when the system is turned off. 

2. Keep diskettes away from magnetic fields (transformers, AC 
motors, magnets, etc.). Strong magnetic fields will destroy 
information on the diskettes. 

3. Handle the diskette by the jacket only — don't touch any of the 
exposed surfaces. Don't try to wipe or clean the diskette surface; 
you might scratch it and destroy data. 

4. Keep the diskette away from heat and direct sunlight. See the 
"Specifications" section below for storage temperature range. 
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5. Avoid contamination of the diskette with cigarette ashes, dust 
or other particles. 

6. Do not write directly on the diskette jacket with a hard-point 
device such as a ball point pen or lead pencil, as this could 
damage the recording surface. Use a felt tip pen only. 

7. Before inserting a diskette into the Mini Disk drive, be sure the 
motor is off (no LEDs lit and no motor sound). 

8. Store diskettes in a vertical file folder or on a shelf where they 
are protected from pressure to their sides (just as phono 
records are stored). 



If you have problems . . . 

Frequent occurrences of disk I/O errors during disk accesses 
may indicate a worn diskette or some problem with the Mini Disk 
drive or other hardware. Try to isolate the problem by swapping 
drives and diskettes as available. 

If you have a repeated problem with a particular diskette, try copying 
the accessible files onto another diskette. Then erase the faulty 
diskette with a bulk eraser (Radio Shack Catalog Number 44-2 1 0) 
and attempt to format it (see Extended Utilities, FORMAT). 

During the format process, the diskette will be checked for flaws, 
and any defective tracks will be locked out, leaving you with an 
otherwise usable diskette. 



If the Mini Disk drive seems to be at fault (errors during access to 
several diskettes), bring it in to your local Radio Shack store for 
servicing. 
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Specifications - Drives and Diskettes 

Storage capacity (bytes available to user) 

Formatted diskette 83,060 

TRSDOS diskette 58,880 



Diskette Organization 

Tracks per diskette 

Bytes per track 
Sectors per track 
Bytes per sector 

Data transfer rate 

Average access time 
Drive motor start time 

Required media 



Diskette life* 



Data storage life 
on diskettes 

Diskette storage temperature 



35 

2560 

10 

256 

12.5K bytes/second 

750 mS 
1 second 

Radio Shack Flexible Diskettes, 
Catalog Number 26-305, or 
26-0405 (pkg of 3) 

2.5 x 10 6 passes/ track (110 hrs) 
5 years estimated actual use 

20 years 



50-125 deg.F (12-52 deg.C) 



Size 

Drive unit 

Diskettes (jacket size) 
Power requirements 



6-3/8 x 3-1/2 x 13-1/4" 
(16.2 x 8.4 x 33.7 cm) HWD 
5-1/4 x 5-1/4 x 1/32" 
(13.3 x 13.3x0.08 cm) HWD 

1 20 VAC, 60 Hz, 35 Watts (28 VA) 



* Typically, diskette life will be limited by improper handling. 
Follow handling recommendations listed above for maximum 
diskette life. 
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Making a TRSDOS BACKUP 

Before you do anything else with your TRSDOS diskette, follow these 
instructions for making a "safe copy" of your system software. That 
way, if anything should happen to your original, you won't be "out 
of business" while you wait to get another one. 

Connect the Mini Disk system and power it up as described in the 
Mini Disk Operation chapter. Be sure your TRSDOS diskette is in 
Drive when you turn on the CPU. (And just for safety, leave the 
write protect tape on the TRSDOS diskette until you've duplicated 
it.) 

If you have more than one drives connected, place a blank diskette 
in drive 1. If not, have the blank diskette handy — BACKUP will tell 
you when to insert it into drive 0. Do not place a write protect tape 
on the blank diskette. 

After you power on the CPU, the display will read 

TRSDOS - DISK OPERATING SYSTEM - VER 2. 1 
DOS READY 

Type: 

B8COT HEED 

The system will then display: 

TRSDOS DISK BACKUP UTILITY VER 2. 1 

If you have only 1 drive connected, type: 

SOURCE DRIVE NUMBER ? 8 L^IIa Ui 
DESTINATION DRIVE NUMBER ? 8 SZHID 

If you have two or more drives, type: 

SOURCE DRIVE NUMBER ? l^jj jj 
DESTINATION DRIVE NUMBER ? 1 \£M£1 

Now type in the date in MM/DD/YY form. For example, if it's 
August 3, 1978, type: 

BACKUP DATE <MM/DD/YY> ? 88/83/T8 [^U^J 

TRSDOS will then start the BACKUP procedure. First it will format 
the blank diskette, locking out any defective tracks; then it will 
duplicate the contents of the TRSDOS diskette onto it. 
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If you are using only one drive, BACKUP will tell you when to insert 
the destination (blank) diskette, and when to re-insert the source 
(TRSDOS) diskette. During the BACKUP process, you will have to 
swap the two diskettes several times. 

When the process is completed, the message: 

BACKUP COMPLETE - PRESS ENTER TO CONTINUE 
will be displayed. 
If TRSDOS instead displays the message: 

BACKUP REJECTED DUE TO C . . > 

then erase the diskette with a bulk eraser (Radio Shack Catalog 
Number 44-210) and repeat the BACKUP procedure. If it still won't 
work, you may need to try using another blank diskette. 



IMPORTANT NOTICE 

The BACKUP utility is provided solely for your personal use in 
maintaining safe copies of your TRSDOS and data diskettes. 
BACKUP automatically places copyrighted TRSDOS software 
onto each destination disk. TRSDOS users may BACKUP the system 
software solely for personal use. 

See the Copyright Notice at the beginning of this Manual for more 



2-17 



TRSDOS 
An Overview 




Contents of This Section 

Introduction 2 

Entering a Command 5 

File Specification 6 



Section 3 - Page 1 



TRSDOS Overview 



Introduction 



TRSDOS, like the entire TRS-80 Microcomputer System, is designed 
to satisfy a broad range of users, including: 

• The novice to computers, who wants to start simply and learn 
the details gradually 

• The experienced programmer, who expects to write complex 
programs, and may want to use some of the system routines 
on a machine language level, to accomplish a variety of 
sophisticated, customized applications 

• The pure "user", who is only interested in using programs, not 
writing them (for example, a clerk using an inventory program 
on the office TRS-80). 

What Is an Operating System? 

By the time you finish this book, you'll have a pretty good idea . . . 
But for the time being, here's an overview. 

An operating system is a master program that allows a complex 
computer system, including various Input/Output (I/O) devices, 
storage devices and programs, to interact efficiently and with 
apparent simplicity. The operating system makes sure everything 
that has to be done, gets done — and you don't even have to know 
what it is that "has to get done"! 

Here's a rather arbitrary breakdown of what an operating system 
does (see Glossary for unfamiliar terms): 

• Interfaces the central processing unit (CPU) with the various 
input/output and storage devices 

• Accepts and interprets operator commands 

• "Shepherds" your programs (and system utilities you request) 
in and out of the execution sequence, by allocating CPU time, 
I/O channels, storage and other system resources 

• Handles interrupts, and oversees the execution of both 
foreground and background tasks 

• Provides fundamental routines which would otherwise have to 
be included in every program; this saves memory and pro- 
gramming time 
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You don't always have to be aware of the operating system to use it. 
For example, when you're using DISK BASIC, you don't see 
TRSDOS at all. But the system is still there, executing a program 
called BASIC; BASIC, in turn, executes your own programs and 
commands. 

At other times, the operating system may be quite visible to you, 
allowing you to enter system commands directly. This is the case 
with TRSDOS and its "DOS READY" mode. 



What Is TRSDOS? 



The TRS-80 Disk Operating System (TRSDOS) is a comprehensive 
set of system routines and file management utilities. Much of its 
complexity (and power) relates to the fact that it is disk-based. 

The system is loaded from diskette, and uses diskettes to store 
internal bookkeeping information as well as data and programs you 
create. TRSDOS uses completely dynamic disk space allocation, 
so you can open and manipulate files freely without worrying where 
they are physically located on the diskette. When a file fills the 
space currently allocated to it, TRSDOS automatically finds and 
acquires more space to accommodate additional data (assuming 
space is available on the diskette). 

(All information on a diskette — programs, data, and TRSDOS 
itself — exists in the form of files. For more information on files, 
see the Glossary, Files Entry, and the Technical Information chapter.) 

In addition to system routines which perform the functions 
described above under "What is an Operating System?", TRSDOS 
includes several file management utilities to let you manipulate and 
modify existing files on the diskette: copy, append, rename, change 
the protection status, etc. 
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How TRSDOS uses RAM 



TRSDOS consists of: 

• an executive program file 

• auxiliary system-routine files 

• a library-command file 

• extended utility files (BACKUP and FORMAT) 

• and the DISK BASIC file. 

The executive program is loaded into RAM on power-up, and remains 
there at all times while TRSDOS is running. For this reason it is 
called the "resident" TRSDOS program. It includes certain system 
routines, tables, pointers, and Input/Output drivers. 

The auxiliary system files contain routines and commands which 
are loaded as needed to execute your commands and programs. 
These routines load into an "overlay" area of memory. When 
TRSDOS has executed the routine, another one may be loaded in 
the same area, or "overlayed". The use of overlays means that 
execution of system routines will not affect your memory area 
(addresses above 5 IFF hex). 

The library command file contains the routines for executing most 
of the operator commands. These routines load into memory 
addresses from 5200 to 6FFF. Therefore your machine language 
programs should generally be located above 6FFF. That way they 
won't be affected by execution of the library commands. 

The TRSDOS extended utility programs are loaded when you type in 
their file names, BACKUP and FORMAT. These programs can use 
all available memory — even the resident TRSDOS program is wiped 
out when they are loaded. 

DISK BASIC is a set of enhancements to LEVEL II BASIC. When 
you type in its file name, BASIC, it will load into memory beginning 
at 5200, and" begin execution. 
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Entering a Command 

Whenever the prompt, 
DOS READY 

is displayed, you may enter an operator command. In its simplest 
form, an operator command is just a single word - a system or library 
command, the name of an extended utility program, or the name of a 
user command program. All these categories will be detailed later. 

As an example, 

dip. Q2QH1 

tells TRSDOS to display the user file directory for drive 0. 

In general, operator commands will require more than one word; 
for example, to kill (delete) a certain file, you have to specify the 
file name. 

-kill xy2 nana 

tells TRSDOS to find the file named XYZ, eliminate it from the 
directory of the diskette which contains it, and release the space 
occupied by that file. 

In general, an operator command consists of a command followed by 
one or more file specifications, followed by special parameters: 

command [Wespec] [^(param)} [tfTO] [tyfilespec] [^(param)} 

where filespec is a valid TRSDOS file specification (more below) 
param is a parameter which details how the command affects the 
specified file(s). 

If this command format seems complex, don't worry; that's because 
it's so generalized. The actual commands can be quite simple, as 
you'll see from the examples given with each command. 

Whenever you finish typing in a command, press 1^113 il . 
TRSDOS will then process the command as follows: 

1) Check to see if it's a system or library command; if so, execute 
it immediately . . . otherwise 

2) Check to see if it's the name of a utility program; if so, execute 
it via the extended utility package . . . otherwise 

3) Examine the diskette directory on each drive to see if the 
command is listed as a user command file; if so, load and 
execute the file. 
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File Specification 



A file specification (filespec) is the way you reference a particular file, 
whether you're operating under TRSDOS, DISK BASIC, or any other 
command program (e.g., TAPEDISK). 

Disk file specifications have the following format: 



name[/ext] [.pw] [:d] 
where 

name is the file name, consisting of from 1 to 8 alphanumeric 
characters, the first of which must be alphabetic 

ext is an optional extension of the name, consisting of from 
1 to 3 alphanumeric characters, the first of which must be 
alphabetic. The extension, if used, must be preceded by a 
slash symbol. 

pw is an optional password, consisting of from 1 to 8 alpha- 
numeric characters, the first of which must be alphabetic. The 
password, if used, must be preceded by a period symbol. 

:d is an optional drive specification, with d equal to 0,1,2 or 3, 
depending on which drive you wish to specify. The drive 
specification, if used, must be preceded by a colon. 



Do not embed blanks in a file specification. If you do, TRSDOS 
will terminate the filespec at the first blank; if the truncated filespec 
is valid, you won't receive an error message. 



Valid file names: 

A 

GAMES/BAS 
PAYROLL/B AS .SESAME 
DRIVECHK: 1 

AUG 1578 



INVNTORY 
SORTER/ VR1 
SECRETS .MYNAME 
DRIVECHK: 2 
TAXES/TXT TEAP ARTY: 1 



DATA 11 
SORTER/VR2 
POETRY/TXT: 1 
AUG3078/DAT.JQD 
CHKWRITR/B AS .VERSION2 



To take a completely "filled out" filespec, 
TAXES/TXT.TEAPARTY: 1 refers to a file named TAXES, with 
an extender TXT, and a password TEAP ARTY. This file is 
referenced to drive 1 . If you are creating a file under that filespec, 
it will be placed on drive 1 . If you are reading or writing to the 
file specified, TRSDOS will reference drive 1 for the file. 
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What makes a particular filespec unique? 

The name, extension and drivespec all figure into the uniqueness 
of a particular filespec. The password does not. 

For example, the following filespecs refer to distinct files: 

A A/BAS A/CMD 

DRIVECHK:0 DRIVECHK:1 DRIVECHK:2 DRIVECHK:3 

However, the following filespecs cannot be used to reference 
distinct files: 

RECEIPTS RECEIPTS.AUG3078 RECEIPTS.AUG3 1 78 

(There are cases where two different passwords are used to access 
the same file; see TRSDOS Library Commands, ATTRIB.) 



More on Extensions 

The particular extension you use can be purely arbitrary and 
personalized. Used this way, extensions give you an extra three 
characters to work with in creating a suitable file name. 

Examples: 

PAYROLL/AUG PAYROLL/SEP PAYROLL/OCT 

However, extensions become more meaningful when they are used 
as type specifiers, using some convention. Here's a recommended 
set of extensions: 

/BAS BASIC program file stored in compressed format 

/TXT ASCII text: BASIC program saved in ASCII form, or 
source file, etc. 

/CMD machine language command file 

/CIM core (RAM) image file, not necessarily executable 

/REL relocatable machine language program file 

/SYS system program - files which are part of TRSDOS. Don't 
use for your files. 

/OVn overlay number n 
/DVR I/O driver module 
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One advantage of this usage is that anyone looking at a directory 
listing of a diskette will know what kinds of programs he's 
looking at. 

Another advantage is that TRSDOS is equipped to recognize 
certain extensions. For example, if a file has the extension /CMD, 
then TRSDOS will load and attempt to execute that file when 
you type: 



filename \l?lt*\A 

omitting the extension /CMD. 

That's why you can execute the file BASIC/CMD by typing 

BRsic nana 

Similarly, your own programs can be written to recognize 
extensions. 



More on Drive Specifications 

If you give a drive specification, TRSDOS will use the specified 
drive in executing the command. If you omit a drivespec, 
TRSDOS will search through the directories of all drives in use, 
starting with drive 0; the first drive with the correct name/ 
extension wiil be used. However, if the command requires a file 
creation, TRSDOS will skip over to the first non write-protected 
diskette. 

For example, suppose four files named DRIVECHK are contained 
on drives through 3. Then every reference to DRIVECHK (no 
drivespec) would go to drive 0. The filespecs DRIVECHK:0, 
DRIVECHK: 1, DRIVECHK:2, DRIVECHK:3, would allow each 
of the four files to be accessed. 



More on Passwords 

The password is assigned when the file is created, and may be 
changed via the ATTRIB or PROT commands. Files with 
passwords can only be accessed by reference to the password, or 
to the diskette's Master Password. So if you assign a password to 
a file, don't forget it! 

It's important to realize that every file has a password, even if you 
do not specify it explicitly when the file is created. In such cases, 
a field of 8 blanks becomes the password. 
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For example, if SAMPLE (a file with no explicit password) exists 
and you attempt to create a new file, SAMPLE.WATERBOY, 
TRSDOS will give you a FILE ACCESS DENIED message, since 
in effect you're trying to access an existing file with the wrong 
password. The correct password is a string of 8 blanks — which 
you can omit from the file specification, since 8-blanks is the 
default password. 
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System Commands 



These three commands (BASIC2, DEBUG, TRACE) leave user 
RAM (hex address 5200-End) "untouched". The necessary code 
for these commands loads into the overlay area between the 
resident program and hex 5200. The other commands, referred to 
as library commands, use addresses between hex 5200-6FFF. 
So locate your machine-language routines above hex 7000 to protect 
them from the utility commands. 



B ASIC2 (jump to LEVEL II BASIC) 



BAS1C2 



This command has no arguments or parameters. It simply transfers 
control to LEVEL II BASIC. Once it has been executed, TRSDOS 
is no longer resident in RAM. Your TRS-80 will then function as 
a LEVEL II machine. 

You may want to do this to gain memory for programs which 
don't require disk capabilities. Another possible application 
would be to LOAD a machine language routine from disk into 
high memory, and then jump to LEVEL II BASIC via BASIC2, 
so you can access the routine from LEVEL II, via a USR function. 

Example: 




MEM0RV SIZE? EZQH] 

RRDI0 SHACK LEVEL II BASIC 

READY 

X. 

To re-load TRSDOS, press the Reset button or type 
SVSTIH USES 

*? /e nana 
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DEBUG (real-time debugging program) 



DEBXJGiUpamm)] 

where param = ON or OFF, and ON is the default. 



DEBUG is a real-time debugging package for use with machine 
language programs, including both foreground tasks and back- 
ground programs. (See Glossary.) DEBUG lets you examine and 
alter the contents of the Z-80 registers and RAM locations; 
jump to specified addresses and begin execution with optional 
breakpoints; step through programs one instruction (or one 
CALL) at a time, and more. 

All address and byte values in this DEBUG section are given in 
hexadecimal form — which is the form required by DEBUG. 



DEBUG loads into the overlay area; addresses above 5 IFF are 
unaffected. 

Type: 

debug Ezma 

to enable the debugging facility. Normal TRSDOS command 
interpretation continues; but the debug program is now set to 
load and execute under any of the following conditions: 

1. When the BREAK key is pressed. 

2. After a program is loaded and before its first instruction 
is executed. 

3. Upon detection of a disk-related error. 

Note: TRSDOS system routines and execute-only user routines 
cannot be fully debugged: you can use DEBUG to examine/alter 
register and RAM contents, but not to single-step, jump, etc., when 
these protected programs are the "targets" for DEBUG. Furthermore, 
since DEBUG loads into the overlay area of RAM, you can't use it 
with other overlay programs and routines. 

DEBUG offers two display formats: 

register display with indirect RAM 

plus any 64-byte "page" of RAM; 
full screen, 256-byte page of RAM. 
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In the register display format, DEBUG displays all the Z-80 registers, 
organized for interpretation either as two 8-bit registers or as 16-bit 
register pairs. Since most programs use several sets of register pairs 
as indirect pointers or indexing registers, 16 bytes of indirect data 
are presented with each register pair. Each of the flag registers is 
shown with an ASCII representation of its flag bits. 

An additional 64 bytes of memory are displayed in four lines at the 
bottom of the display. 

Here's a typical DEBUG display sequence. Note that the values in 
your display will typically vary from these. 
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In this display, register B contains the hex value OA, and register C 
contains 3E. Taking the BC register pair as a pointer, it points to 
address 0A3E. Therefore, the contents of memory locations 0A3E 
through 0A4D are shown to the right of the BC = 0A3E =>marker. 
In this case, address 0A3E contains 09, 0A3F contains BA, etc. 

The flag registers F and F' are handled differently. For these 
registers, the hex contents of the flag register is displayed, along with 
a bit-by-bit alphabetic code which makes it easier to interpret the 
flag status. For example, bit 7 (leftmost bit) is the sign bit, so the 
alphabetic code shows an S in that position whenever this bit is "set". 
Here's a complete table of codes for all the flag bits: 

if not set 



bit status 


if s< 


7 Sign 


S 


6 Zero 


z 


5 unused 


1 


4 Half-carry 


H 


3 unused 


1 


2 Parity/overflow 


P 


1 Negative 


N 


Carry 


C 



In the above display, none of the F flag bits are set (discounting the 
unused bits 5 and 3), and all of the F' flag bits are set. 

Notice the four additional lines below the PC register display. Each 
line shows the contents of 16 bytes, starting at the address to the left 
of the arrow; the four lines always show a total of 64 bytes of 
contiguous memory i.e., locations with sequential addresses. The 
starting point in this four-line display is either 0000 or the last 
command you specified with the D command (more later.) 

The blank area in the lower left of the Display is where commands 
you enter will be displayed. 
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DEBUG Commands 

Note that some commands are executed as soon as you press the 
specified command key ; other co mmands are executed only when 
you hit < SPACE > or l^lian , as indicated below. 



Command 



Entry 
Required 



Operation Performed 



A 



C 



Daaaa 



Gaaaa[,bbbb[,cccc]] ia:tian 



H 



M[aaaa[ 



none Shows the ASCII or graphics 

character corresponding to each 
value displayed. Shows a period 
when the value is not displayable 
as an ASCII or graphics character. 

none Single-steps next instruction, with 

CALLS executed in full. (Next 
instruction is defined by PC 
register.) Target program cannot 
be a system or execute-only file. 

<SPACE> Sets memory display starting 
address to aaaa. In full screen 
mode, sets starting address so 
aaaa is contained in display. 

Place aaaa in PC register and 
executes with optional 
breakpoints at bbbb and cccc. 

Displays all memory and register 
values in hexadecimal form. 

Single-steps next instruction 
(defined by PC register). Target 
program must not be read- 
protected. 

< SPACE > Sets the current modification 

address to aaaa. The modification 
dialog will then be displayed in 
the lower left of the screen. If 
aaaa is omitted, the last modifica- 
tion address will be used for aaaa. 
If aaaa is currently in the display, 
its contents will be surrounded 
by a pair of vertical bars. 



none 



none 
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Command 



Entry 
Required 



Operation Performed 



Rrptydddd <SPACE> Loads register pair rp with the 

value dddd. 

rp may be any register pair: AF, 
BC, AF', BC, IX, IY, PC, etc. 

S none Sets display to full screen 

memory mode, showing 256 
contiguous bytes. Press X to 
return to register display format. 

U none Dynamic display update mode: 

lets you observe the execution 
of a foreground task. Hold down 
any key for a couple of seconds 
to exit this mode. 

X none Sets display to register format; 

also cancels any command you 
are in the process of entering, 
except R-command. 

; none Increments memory display by 

one page (in register display 
mode, page = 64 bytes; page = 
256 bytes in full screen mode). 

— none Decrements memory addresses 

displayed by one page. 

Note: You cannot use the backspace key ( «- ) to delete mistakes 
made while entering commands. Instead, just hit the X key to 
cancel the command. Or, if you made the error while typing an 
address or value, just type the correct address immediately after 
the incorrect address. DEBUG will only look at the last four 
digits entered. 

For example, 

D474680 < SPACE > 
tells DEBUG to display the page of memory containing address 4080. 
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More on the M-command (modify memory) 

Any time you wish to alter the contents of a memory location, type 
Maaaa and press the < SPACE> . This sets the memory modification 
address to aaaa and puts a memory modification prompt in the lower 
left corner of the Display. For example, typing 
M7F06 < SPACE > 
produces: 



7F88 => 
7F88- 7F16 => 
28-_ 7F20 => 

7F38 => 



1201180 00 00 80 80 32 B2 

B3 63 B3 EG EG B3 EG EG 

FB BB BB BB BB FB FB BB 

88 FB FF FB FF FB FF FF 



28 B3 B3 B3 B3 



b: 



BB B3 BB EG BB B3 BB BB 
08 FB FB FB FB FB FB FB 
00 FF FF FF FF FF FF FF. 



Note the vertical bars around the value of 7F00; These will appear 
wherever the modification address appears on the screen. 

To modify the contents of 7F00, type the new, two-digit contents 
and press < SPACE >. The display will then be updated, and 
DEBUG will increment the modification address by one. 

To leave an address contents unchanged, simply press < SPACE > 
without first entering a new contents. This will increment the 
modification address and leave the previous address unchanged. 

To exit the modify memory mode, type X or UflM*H . 

If you simply type: 

M < SPACE > 

DEBUG will default to the last specified modification address, if any: 

otherwise 0000 will be used. 

Frequently, two values on the display will be highlighted by vertical 
bars - one in the 64-byte memory display area, and another in the 
indirect memory area associated with the register pairs. 

This is because the contents of the modification address happens to 
be displayed twice, one directly, one indirectly. 
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More on the G-command 

To return to TRSDOS from DEBUG without re-initializing, type 

G462D Wkid-A 

DEBUG will then be re-entered under any of the three conditions 
noted above. 

To disable DEBUG after using this exit, type 
DEBUG <0FF> IdJHdzl 
DIP. HJkJJ;! 

To begin execution at the address in the PC register (while you're 
in the DEBUG mode), type 

g QUOD 

To reinitialize TRSDOS, type 
G6000 QZEQaI 

More on the U-command (update display) 

In the Update mode, only foreground tasks are executed. So to see 
anything happening, you need to look at registers or memory 
locations used by a foreground task. 

The real-time clock makes a good example. 

Type: 

D404S < SPACE > 

to display the values 4040 through 4046. These addresses store the 
time and date, as follows: 



4040 


25mS real-time scheduling counter 


4041 


seconds 


4042 


minutes 


4043 


hours 


4044 


year 


4045 


day 


4046 


month 



Now hit U and you'll see the values updated by the clock foreground 
task. 
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Other applications for DEBUG 

DEBUG can be accessed via DISK BASIC, to help you locate stack 
pointers, table addresses, etc. See DISK BASIC. 

DEBUG is also a handy way to create short object code programs, 
which can then be DUMPed onto diskette. 

To disable DEBUG 

As long as DEBUG is in the overlay area, TRSDOS may enter the 
debugging program unexpectedly, for example, upon an error. If 
you don't want this to happen, disable DEBUG by typing: 
G492D Id^iJ-J (to return to TRSDOS) 

DEBUG (OFF) EHUD 

dir EZQia 



TRACE (dynamic display of PC register) 



TRACE[Kparara)l 

where param = ON or OFF; ON is the default. 



The TRACE command enables a foreground task which displays the 
contents of the user's program instruction counter (PC register) in 
the upper right of the Video Display. The 4-digit hexadecimal value 
will be updated every eight milliseconds with the current background 
program's execution address. For example: 

trace mma 

Since it is a foreground task, TRACE operates at all times - in DOS 
READY mode, DISK BASIC, or any other program. To temporarily 
disable TRACE, disable all interrupts (CMD'T" in DISK BASIC). 
When interrupts are re-enabled CMD"R" in DISK BASIC, TRACE 
will start up again. 

Used with the DEBUG program, TRACE can be invaluable in 
debugging machine-language programs. It won't be of much use 
during BASIC program execution, though. To permanently stop 
TRACE, execute the command: 

TRACE <0FF) QZEQ3 
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Library Commands 

These commands are overlayed into the RAM area hex 5200-6FFF. 
They are loaded as requested in blocks; so, for example, DATE and 
TIME are both loaded when either is requested. TRSDOS will not 
waste time loading a command if the code is already in RAM . 

AUTO (automatic key-in on power-up) 



AUTO [^dos-command] 

where dos-command is a fllespec for an operator command 
or an executable command file. 



Note: To use AUTO, you must remove the write-protect tab from the 
system diskette. 

The AUTO command lets you modify the power-up sequence, by 
specifying a command to be executed immediately after power-up. 

Typing: 

AUTO dos-command ia^iia;i 

causes TRSDOS to write dos-command as an "automatic key-in" 
on the drive diskette, replacing any previous automatic key-ins. 
From that point on, every time you power up using that TRSDOS 
diskette, dos-command will be keyed in automatically whenever 
TRSDOS is initialized. An automatic key-in takes the place of 
keyboard input. 

To restore the power-up sequence to normal, type: 

AUTO umaj 

This will eliminate any automatic key-ins. 

Examples: 

AUTO CLOCK on subsequent power-ups, the display clock 

command will automatically load and execute. 

AUTO BASIC on subsequent power-ups, TRSDOS will load 

DISK BASIC and begin the initialization dialog. 

NOTE: You can override any automatic key-in by holding down the 
QSSOQ key during power-up. This may be your only way of 
regaining control of the system, for example, if dos-command is not 

a working command program. 
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ATTRIB (set protection attributes) 



param 
I 

ACC=pswl 
U?D=psw2 
VROT=level 



ATTRlBljsfilespecfyiparami, param . . .]) 

where param can be any of the following: 
meaning 

make file Invisible to normal Directory command 
assign pswl as the new access password 
assign psw2 as the new update password 



assign level as the new access protection level: 
(KILL, RENAME, WRITE, READ, EXEC) 



The filespec must exist on one of the connected drives. 

This command lets you alter the protection status of a file, by 
changing passwords and/or the degree of access granted by a 
password. (See TRSDOS Overview, "File Specifications" section.) 

Specifying the 1 parameter gives the file the invisible attribute. To 
display Invisible files in the Directory, you have to specify the 
I parameter in the DIR command. There is no way to remove the 
I attribute, short of copying the file to a new file which does not 
have the I attribute. 



Example: 




fTfTRIS VtDSCrWtH>:l <D Mhiiil 

DOS RERDV 

dir i USED 



FILE DIRECTORY DRIVE 1 




CHESS/CMD P 



DOS READY 

I>1R :i (DHJH33 



MENU/TXT 



MflNURL -- 09/81/7 



TEST/BflS 
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- DRIVE 1 MANUAL — 09/01/78 
VIDSCflN/CMD I MENU/TXT 



CHESS/CMD P 
TEST/BRS P 

DOS REflDV 



All files are protected with two passwords, an access and an 
update password. Access and update passwords may be identical, 
and they may consist of all blanks. Use of the update password 
grants total privilege to a file - you can kill, rename, write, etc. 
Use of the access password, on the other hand, grants a limited 
privilege, as specified by a PROT parameter in the ATTRIB 
command. 

The protection levels form a hierarchy, and each level implies 
access to all lower levels. 



level 



privilege 



KILL 

RENAME 

WRITE 

READ 

EXEC 



total privilege 

rename, write, read, execute 

write, read, execute 

read, execute 

execute only 



When you create a file, the password you specify becomes both 
the access and the update password. (If you don't specify a 
password, a string of 8 blanks is assigned as a default password 
for both access and update.) 



To 
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Once you have created the file, you can use ATTRIB to assign 

different values to the access and update passwords. Having 

two different passwords can be very useful in business applications. 

For example, suppose you have a data file, PAYROLL, and you 
want an employee to use the file in preparing paychecks. Assume 
the file was created with default (blank) passwords. 

Then: 

RTTRIB PflVROLL (RCC=EMPLOVEE, UPD=MRNRGER, PR0T=RERD> 

would allow the EMPLOYEE to read the file, while only 
MANAGER could alter it. 

To delete a password (set it to blanks), omit the password after 
the equals sign in the password specification. For example, 

RTTRIB PAYROLL MRNRGER <RCC=> 

sets the access password to blanks, and leaves the update password 
unchanged. 

Note: To access a file from DISK BASIC requires a privilege of 
READ or higher. 

CLOCK (display real-time clock) 



CLOCK[Kparam)l 

where param=ON or OFF; if no param is specified, 
ON is assumed. 



Typing: 

CLOCK QZEQa 

causes the internal real-time clock to be forcibly displayed on the 
top line of the Video Display (PRINT positions 53-60). Any 
characters present at those locations will be overwritten. 

The clock display is updated once a second via a "foreground task". 
In other words, as long as the interrupts are enabled, TRSDOS 
will periodically interrupt whatever "background program" is 
executing (DISK BASIC, TAPEDISK, etc.), and update the clock 
display. 

TRSDOS powers-up in a CLOCK OFF condition. 
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To stop the display -clock function, execute the command: 
CLOCK <0FF) 021133 

See TIME command for information on the real-time clock. 

COPY (make a duplicate file) 



COVYWlespecl fYOWlesped 



Creates a duplicate of filespecl under the new namQfllespec2. If 
filespec2 already exists, its previous contents are lost. The first 
file (filespecl) is unchanged by this command. 

You must have at least two disk drives to copy a file from one 
diskette to another. 

Examples: 

COPY PfiGE7/TXT:0 TO PRGE7/TXT : 1 
duplicates PAGE7/TXT on drive onto drive 1, using the same 
name/extension. 

COPY OLDFILE/BRS. PDQ TO DERDFILE 
duplicates OLDFILE under the name DEADFILE. Note that 
OLDFILE is protected by a password, while DEADFILE is not. 
DEADFILE will be created on the first non write-protected 
drive in the sequence 0-3. 



DATE (set date) 



DATE$mm/dd/yy 

where mm is a 2-digit month specification, mm=01 to 12 
dd is a 2-digit day specification, dd=01 to 3 1 
yy is a 2-digit year specification, yy=00 to 99 



For example, if it's August 3, 1978, type: 
DATE 68/03/78 SUED 

This command resets the real-time date. At power-on, the date 
is set to 00/00/00. The date is updated each time the clock 
cycles through a 24-hour period. The real-time clock calendar 
includes the logic to account for 28, 29, 30 and 3 1-day months. 
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DEVICE 



DEVICE 



This command has no arguments or parameters. It simply lists all 
currently defined I/O devices: KI=keyboard, DO=video display, 
PR=line printer. 

device moa 

DIR (display directory) 

Example: 



DIR[$:<i] [${param[,param ...])] 

where :d = a drive specification, <i=0,l,2 or 3, and 
is the default 
param = any of the following: 



param 

S 
I 

A 



meaning 

display all System and non-Invisible files 
display all Invisible and non-System files 
display disk space allocation for all files displayed 



This command reads and displays the file directory of a specified or 
assumed drive. If no parameters are specified, only non-Invisible user 
files will be displayed. 

Disk space allocation is indicated as follows: LRL (logical record 
length), EOF (end of file, i.e., highest record number used), and 
SIZE (measured in GRANules, where 1 granule = one-half track, 
or 1.25K bytes). 

Examples: 



DIR H^=l;l 

displays all user files on drive 0. A typical output for this command 
might be: 



FILE DIRECTORY DRIVE 6 



TRSDOS 



VIDSCRN2/CMD 
TBUG/CMD 
LISTER/BfiS 
DISKDUMP/BRS 

DOS READY 



CLKfiXESS/BflS 
EDTfiSM/CMD 
TRPEDISK/CMD 
GLOSSfiCC/BflS 




SELECTRC/DVR 
QLOSSflRY/BflS 
KBFIX/CIM 
VIDSCfWCMD 
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DIR :1 <I.>S) QZH13 

displays all files, including System and Invisible files. A typical 
output for this command might be: 



-- DRIVE 1 




MANUAL — 09/61/78 

CHESS/CMD P 



DIR/SVS SIP 
TEST/BAS P 



DOS READY 




Note the P beside some files. This indicates they have non-blank 
passwords. 

dir <r> BZES3 

gives the disk space allocation on drive 0, user files only. Typically: 



FILE DIRECTORY -- 


- DRIVE 





TRSDOS 


— 11/18/78 




EDTASM/CMD 


LRL= 


256 


/ E0F= 


27 / SIZE= 


6 GRANS 


RSM/CMD 


LRL= 


256 


/ E0F= 


18 / SIZE= 


4 GRANS 


VHMTBUG/CMD 


LRL= 


256 


/ E0F= 


/ SIZE= 


2 GRANS 


SEQCHECK/TXT 


LRL= 


256 


/ EOF* 


2 / SIZE= 


1 GRANS 


TBUG/CMD 


LRL= 


256 


/ E0F= 


5 / SIZE= 


2 GRANS 


TAPEDISK/CMD 


LRL= 


256 


/ E0F= 


2 / SIZE= 


1 GRANS 


CPRINT/BAS 


LRL= 


256 


/ E0F= 


1 / SIZE= 


1 GRANS 


HMRSM/CMD 


LRL= 


256 


/ E0F= 


18 / SIZE= 


4 GRANS 


DOS READY 














If a Directory listing cannot fit on the screen, only the first 1 2 lines 
will be displayed. Press any key to see the remainder of the listing, 
in increments of 16 lines. 
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DUMP (dump memory to disk) 



DUM?]f)filespecUSTART=X'aaaa',END=X'hbbb'[,TRA=X'cccc']) 

where aaaa, bbbb, cccc are 4-digit hexadecimal addresses 

aaaa = starting point in RAM of the machine 
language program or data block to be 
dumped to disk; aaaa must be greater than 
6FFF. 

bbbb =ending point in RAM of the block; bbbb 
must be no smaller than aaaa 

cccc = transfer address; when TRSDOS attempts to 
execute the file, it will start at cccc. If cccc 
is omitted, 402D will be used. This is the 
address of the normal re-entry into 
TRSDOS (i.e., re-entry with DOS READY 
displayed; no re-initialization). 



If filespec already exists, its previous contents will be lost. 

If filespec does not include an extension, TRSDOS will automatically 
assign the extension CIM (core image) to the file. 

Once you have dumped a machine language program onto disk, there 
are two ways to execute it. 

1) Simply type filespec EEJEa . TRSDOS will load the 
file and begin execution at the transfer address. 

2) Type DEBUG \£M£A and then filespec IdflHd:! 
After TRSDOS loads the file, it will enter trie DEBUG 
package. PC will contain the transfer address. You can 
then single step the program (I command), call-step 

(C command), or execute it in full by typing: 

g nana 

Note: A file with the extension /CMD can be loaded and executed 
simply by typing the file name, without the extension, and 
pressing HMH;1 . TRSDOS will supply /CMD as a default 
extension. 

Examples: 

DUMP GRAPHICS < STRRT=X X 7000 ', END=X'70fl8 MRfl=X' 7006 O 
DUMP DRTfl/CIM:! <. STflRT=X" 8000 ', END=X' 8050") 



4-18 



TRSDOS Commands 



KILL (delete a file) 



KILLtyfilespec 



This command deletes the specified file and frees the space for use 
by the system. 

If no drivespec is included in thQfilespec, TRSDOS will search for 
the first drive which contains filespec, and attempt to delete that 
file. If the diskette is write-protected, TRSDOS cannot KILL the 
file. 

Example: 

KILL OLDFILE/BRS. PASSWORD 



FREE (display free space on all drives) 



FREE 



This command has no arguments or parameters. It displays the 
amount of free space remaining on all drives in use, in terms of files 
available and unused granules. (Each diskette can contain up to 
48 user files; data diskettes have 67 granules available for user files; 
TRSDOS diskettes, 44 granules.) 

For example: 




FREE EH3D 

DRIVE — TRSDOS 
DRIVE 1 — TRSDOS 

DOS RERDY 



10/21/78 
10/03/78 



37 FILES, 
33 FILES, 




25 GRflNS 
27 GRflNS 



LIB (display library commands) 



LIB 



Requires no arguments or parameters. This command displays all 
TRSDOS system library commands available. These are the 
commands which load between hexadecimal 5200 and 6FFF. 

For example: 

LIB ozEsa 
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LIST (list text file contents to display) 



LISTtyf ilespec 



Reads the specified file and lists its contents on the Video Display. 
Because LIST gives an ASCII representation of the data in the file, 
filespec should refer to a text file. If you LIST a non-text file, the 
display will be filled with a meaningless sequence of ASCII and 
graphics characters. 

Text files include: 

• BASIC programs saved with the A option 

• data files created by BASIC sequential write (PRINT#n) 

statements 

• assembly language source code; etc. 

To temporarily freeze the Display during LIST execution, hold down 
the SHIFT and @ keys- until the listing pauses; press any key to resume 
execution. TRSDOS will only accept such a pause after listing a 
complete physical record - that's why you need to hold down the 
SHIFT @ keys until TRSDOS "notices" your pause command. 

Example: 

LIST PR0Q1/TXT 

LOAD (load machine language file) 



LOADtyfilespec 



Loads the specified file into RAM and returns control to TRSDOS. 
The file specified must contain Z-80 object code, and normally 
would have been created by a DUMP or TAPEDISK command. 

LOAD is useful for loading several programs into memory, so that 
all of them can then be called by a master program, which may be 
another machine language routine or a BASIC program. (Of course, 
all the different files must load into non-overlapping areas of RAM.) 

To load subsidiary object code programs and then execute them 
via a master object code program, LOAD each of the subsidiary 
programs, then type the master filename and press IdJhdJ;! . 

Examples: 

LORD GRAPHICS 
LOAD DflTR/CIM:! 
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PRINT (list text file to line printer) 

?Rimy>filespec 



Works just like LIST, only the output is sent to the line printer. The 
file should be in text (ASCII) form. 

Examples: 

PRINT SEQCHEK/TXT 
PRINT PflGE?/TXT:0 

PROT (use diskette's master password) 



PROT[$:<i] [fy(param[,param ...])] 

where :d = a drivespec, d=0, 1,2,3; if no drivespec is 
given the first drive is used 
param can be any of the following: 

param meaning 

PW change Master Password 

UNLOCK remove passwords from all user files 

LOCK assign the master password to all user files 



LOCK and UNLOCK are mutually exclusive; use only one. 

This command changes the protection status of all non-System files 
on the specified drive. To use it, you need to know the diskette's 
Master Password, which is assigned during FORMAT or BACKUP. 
The diskette you reference must not be write-protected. 

Note: Your TRSDOS diskette has the password, PASSWORD. 

To change the Master Password, specify PW as a parameter. To 
remove passwords from all user files, specify UNLOCK. To place 
the diskette's Master Password on all user files, specify LOCK. 
(The Master Password then becomes the update and access password 
for those files.) 

Examples: 

PROT :1 (UNLOCK) liflli:! 

After you enter this command, TRSDOS asks for the Master Pass- 
word for the drive 1 diskette. If you enter the password correctly, 
TRSDOS will remove all user assigned passwords from files on 
that diskette. 
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PROT (P14, LOCK) 

After you specify the Master Password correctly. TRSDOS will 
prompt you to enter a new Master Password. This new password 
will be assigned to all user files, since the command included the 
LOCK option. 

A typical display sequence using the PROT command: 




DOS RERDV 

PROT <L0CK> GfflUS 

MASTER PASSWORD ? 

DOS RERDV 



PASSWORD EZma 



FILE DIRECTORY — DRIVE 




TRSDOS — 10/21/78 

EDTRWCMD P RSM/CMD P VIDSCRN/CMD P 

TBUG/CMD P 



VHMTBU6/CMD P 
TAPED ISK/CHD P 



SEQCHECK/TXT P 
HMRSIVCMD P 



DOS RERDV 

Note" that all user files are now protected with the Master Password. 



RENAME 



RENAMEWHenamel[/extl][.psw] [:d]fTO^filename2[/ext2\ 

where filename 1, filename 2 are TRSDOS file names, 
extl,ext2 are extensions 
:d is a drivespec (d=0,l,2,3) 
psw is a password 



This command changes a file's name from the first name/extension 
to the second name/extension. Note that the second name/extension 
should not include a password or a drivespec. The first file's 
specification may include a password and drivespec, as required to 
identify a desired file. 

RENAME cannot be used to change a file's protection attributes 
or to move it to another drive. The previous passwords, protection 
level, and Directory attributes (Invisible for non-Invisible) will be 
assigned to the renamed file, and the file will remain on the same 
diskette. 

RENAME also checks to see that the intended new name does not 
duplicate a filename currently on the same diskette. If it does, the 
command is cancelled and an error message is displayed. 



4-22 



TRSDOS Commands 



Examples: 

RENRME MflTHPflK TO MRTHPRK/BRS 

adds an extension to the filename. 

RENRME RBCDE/DRT TO RBCDEF/DRT 

changes the file name only. 

RENAME PRVR0LL1/TKT. GSR TO PRVR0LL2/TXT 

changes the filename; the password is retained automatically. 

RENRME F I LEI: 3 TO FILE2 

changes the filename of the file on drive 3 only. 

TIME (set real-time clock) 



TIMEtyhh:mm:ss 

where hh is a 2-digit hours specification 

mm is a 2-digit minutes specification 
ss is a 2-digit seconds specification 



This command sets the clock. On power-up, the clock is reset to 
00:00:00. 

Note: TRSDOS maintains a 24-hour/day clock format. After 
23:59:59, the clock starts over at 00:00:00, and the day is 
incremented. 

The current time is stored at locations hexadecimal 4040-4046; 
these values are updated via the realtime clock as long as interrupts 
are enabled. 

Example: 

TIME 08:24:80 
See DATE and CLOCK 
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VERIFY (automatic read-after-write) 



VERIFY [Uparam)] 

where param = ON or OFF; ON is the default. 



verify nana 

causes TRSDOS to verify all user disk writes (for example, file-writes 
from DISK BASIC). This will be useful when you want to be sure 
that no data is lost or altered during a disk write. For example, 
before you COPY a file, you may want to enable VERIFY. 

However, when VERIFY is on, disk accesses are only about 50 
percent as fast as normal. 

Typing: 

VERIFY (OFF) OSES 

disables the automatic read-after-write verification. 

(note that TRSDOS powers up in a VERIFY (OFF) condition.) 

Verify does not affect system table and directory writes; they are 
always verified. 
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TRSDOS Utilities 

These are special programs, not strictly a part of TRSDOS, which 
you can call to perform some very useful functions. Unlike system 
routines and library commands, these extended programs may use 
memory locations above hex address 6FFF; therefore any programs 
you have in RAM may be lost when you load a utility program. 

BACKUP (duplicate a diskette) 



BACKUP[l^;#TOlM2] 

where :dl is a specification for the source drive 

:d2 is a specification for the destination drive 
dl,d2 = 0,\,2 or 3. 



If you omit the drivespecs, BACKUP will prompt you to enter the 
source and destination drive numbers one at a time. 

Tnis utility duplicates an entire TRSDOS or data diskette. You can 
use any two drives for the backup, or you can perform the backup 
using drive 0, by swapping source and destination diskettes when 
BACKUP tells you to. 

If the destination diskette is unformatted, BACKUP will format it, 
locking out any defective tracks, and will then proceed to copy 
all source disk files onto it. (If the destination disk cannot contain 
all the source disk data because of locked out tracks, the backup will 
be rejected.) 

BACKUP will accept a pre-formatted diskette only when its Master 
Password and Diskette Name match that of the source disk. In this 
case, BACKUP will skip the formatting step and begin the copy and 
verify process. If for some reason, BACKUP rejects a diskette, 
erase the diskette with a bulk eraser and try again. 

Examples: 

BACKUP 

BACKUP :S TO :@ 

BACKUP :8 TO :1 

Here's a typical BACKUP sequence, using only Drive 0. 



DOS RERDV 

BftCKUP :8 TO ;8 IdJHd;! 
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TRSDOS BACKUP UTILITY VER 2. 1 
BACKUP DATE (fWDD/YY) ? 16/88/78 
< INSERT SOURCE DISK> 

BACKUP will then prompt you to insert source (original) and 
destination (duplicate) diskettes as necessary. 

When using two drives for the BACKUP, you won't have to do any 
swapping. 



IMPORTAINT NOTICE 

The BACKUP utility is provided solely for your personal use in 
maintaining safe copies of your TRSDOS and data diskettes. 
BACKUP automatically places copyrighted TRSDOS software 

onto each destination disk. TRSDOS users may BACKUP the system 
software solely for personal use. 

See the Copyright Notice at the beginning of this Manual for more 
details. 
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FORMAT (prepare a data diskette) 



FORMAT 



This utility lets you prepare data diskettes containing a minimum of 
system information and leaving you with a maximum amount of 
space for program and data files. (TRSDOS diskettes have 44 
granules/5 5K bytes available for your files; data diskettes, 
67 granules/83. 75K bytes. 

Note: Data diskettes can only be used in drives 1,2, and 3, except 
during a BACKUP or FORMAT. 

FORMAT takes a blank (new or magnetically erased) diskette, 
records track/sector boundaries on it, then initializes it with 
directory and bootstrap files. During the formatting process, 
TRSDOS will let you specify any tracks you'd like to lock out, so 
you can use them for non-TRSDOS files. 

Unless you have another (non-TRSDOS) means of accessing the 
diskette, don't lock out any tracks. 

FORMAT will lock out any defective tracks, to prevent data 
from being lost in these areas. 

If you begin to get READ errors during accesses to a diskette, 
erase the diskette and re-format it. If there are defective tracks, 
FORMAT will lock them out, and you'll be left with an other- 
wise usable diskette. 
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To lock out tracks . . . 

Specify them individually or as a range. 

Example: 

1,3-5 locks out tracks 1,3,4,5. . 

TRSDOS will never try to write to locked-out tracks. 
Here is a typical FORMAT sequence, using Drive 1 . 




DISK FORMATTER UTILITY 



WHICH DRIVE IS TO BE US ED ? i ElZEHO 

DISKETTE NAME ? HfiNUfiL 14UI4J 

CREATION DATE <MM/DD/W ) ? 18/ 6S/F8 Q2QH1 
MASTER PASSWORD ? TRS88 EHUD 

DO VOU WANT TO LOCK OUT ANV TRACK S? V EZE13 
WHICH TRACKS <0-34>? 1,6-8 am3. il 
FORMAT THE LOCKED-OUT TRACKS? H USEE] 
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Auxiliary Utilities 

TAPEDISK (copy tape file to disk file) 

This utility lets you load a SYSTEM tape into RAM, and then dump 
it into a specified file on the disk. (SYSTEM tapes are created with 
the Editor/Assembler, TBUG, or supplied by Radio Shack.) 

Do not attempt to use TAPEDISK to load tape files which load 
below hexadecimal address 54F4 (decimal 21748). TAPEDISK 
uses this area. 

Note: Most Radio Shack SYSTEM tapes designed for use with 
LEVEL II TRS-80's will not work under DISK BASIC, because of 
differences in RAM usage under DISK BASIC and LEVEL II. 

To load and execute TAPEDISK, type: 

TRPEDisK nana 

TAPEDISK will come up with the prompt, 



Any time the prompt is displayed on the current line, you can enter 
one of the three TAPEDISK commands. 

1) Load from tape 



C 



is the command to turn on the Recorder. (To use TAPEDISK, 
you should connect the recorder directly to the TRS-80 tape jack, 
not to the Expansion Interface jack.) 

Type: 

When the file has loaded, you can load another SYSTEM tape, or 
enter another command. 
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2) Dump to disk 



¥tyfilename\lext] [.password] idtyaaaatybbbbtycccc 

where filename is a TRSDOS filename 
jext is an optional extension; 
.password is an optional password specification; 
:d is a required drivespec, d=0,l,2 or 3; 

aaaa is the hexadecimal starting address in RAM; 
bbbb is the hex ending address in RAM; 
cccc is the entry point for execution of the file. 
All addresses are in 4-digit hexadecimal form. 



When you're ready to dump the program from RAM onto disk, type in 
the F command. For example, if the program loaded into RAM 
addresses 7000-70FF, and the entry point is at 700A, you'd type: 



?F USRC0DE/CMD:1 7660 76FF 786fi [12033 

After the dump, the prompt will return. 
3) Exit to TRSDOS 



This command returns you to TRSDOS, via the normal re-entry 
(no re-initialization). 

Below is a typical TAPEDISK display sequence. 



NJbH;i 




?F QfWHICS^T^ 6888 6FFF 482S>EII3a 

TiEZilia 

DOS READY 
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DISKDUMP/BAS (examine disk file) 

This is a BASIC program. To execute it, you must load DISK BASIC 
first, and then load DISKDUMP/BAS: 




Sana 



HOW MflNV FILES? EHUD 

MEMORY sizE?n?ma 

RADIO SHRCK DISK. BRSIC VERSION 1. 1 

RERDV 

RUN"DISH)UMM3RS' RM^il 

DISKDUMP lets you look at the contents of any of your disk files. 
It will help you experiment with various random and sequential disk 
output statements, and also help you to debug disk I/O routines. 

The program is written to dump to the Line Printer. If you do not 
have one connected, change all LPRINTs to PRINTs (lines 
170,240,250) and change line 160 to: 

160 GETi, SN 

This program prompts you to enter the filename and th en to en ter 
the sector you want to examine. You can simply press nana;! 
without a number and the sector-by-sector examination will be 
sequential, starting with sector 1 , the first physical record in the 
file. 

If you specify a sector number higher than the EOF number 
(end-of file), no error message will be given and the "sector" will 
appear as zero-value bytes. 

The sectors are printed 1 6 bytes at a time. These 1 6 bytes are dis- 
played first in hexadecimal code, then with the corresponding ASCII 
code. The ASCII representation is surrounded by ! symbols. Periods 
are substituted for bytes which have no alphanumeric representation. 

Below is a typical DISKDUMP session. 




OlfLjlo 



SECTOR DUMP UTILITY 1. 1 



F1LESPEC: SEQCHECK7TXT 



SECTOR NUMBER (OR 'ENTER-' FOR NEXT SECTOR) : 0300 
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F I LESPEC : SEQCHECK/TXT 



SECTOR: 1 



8 35 26 43 4C 53 3R 26 43 4C 45 41 52 26 31 36 36 

16 36 8D 31 36 28 41 24 3D 49 4E 4B 45 59 24 3fi 49 

32 46 41 24 3D 22 22 54 48 45 4E 31 38 8D 31 35 26 

48 49 46 20 41 24 3D 22 48 22 54 48 45 4E 28 32 35 

64 8D 32 30 20 50 52 49 4E 54 41 24 3B 3R 42 24 3D 

86 42 24 2B 41 24 3fl 47 4F 54 4F 31 38 8D 32 35 26 

96 58 52 49 4E 54 3fi 56 52 49 4E 54 22 44 41 54 41 

112 28 49 40 41 4? 45 26 5? 49 4C 4C 28 41 53 26 4F 

128 4E 28 4E 45 58 54 26 4C 49 4E 45 2E 28 28 22 43 

144 48 52 24 28 39 31 29 22 3D 42 59 54 45 28 44 45 

168 4C 49 4D 49 54 45 52 29 22 8D 33 38 28 46 4F 52 

176 49 25 3D 31 28 54 4F 28 4C 45 4E 28 42 24 29 3fi 

192 28 56 52 49 4E 54 26 41 53 43 28 4D 49 44 24 28 

288 42 24 2C 49 25 29 29 43 48 52 24 28 39 31 29 3B 

224 3fl 4E 45 58 54 8D 33 35 28 58 52 49 4E 54 8D 35 

240 30 28 4F 56 45 4E 22 4F 22 2C 31 2C 22 54 45 53 



5 CLS: CLERR 168! 

6.10 fi*=INKEV$:I! 

FR$=""THEN10. 15 ! 

IF fi$= ,, @"THEN 25! 

.20 F'RINTR*.; :B*=! 

B$+fi$:G0T018. 25 ! 

PRINT :PRINT"DRTR'. 
! IMAGE MILL RS 0! 
!N NEXT LINE. <"C! 
!HR$<91>"=BVTE DE! 
'.LIMITERr.Se FOR! 
!IJi=l TO LEN<B$):! 
PRINT RSC:<MID$<! 
!B$, I%))CHR$<91>; ! 
!: NEXT. 35 PRINT. 5! 
!8 OPEN"OM, "TES! 
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Memory Organization 



The TRS-80 Disk Operating System is comprised of IK of ROM 
resident CIO (Character-oriented I/O) drivers and 4K of RAM drivers, 
schedulers, tables, pointers, etc. The ROM resident CIO drivers are 
also used by LEVEL II BASIC and therefore are part of its 12K 
ROM requirement. 

Since LEVEL II is upward compatible with DISK BASIC, an 
additional 0.5K of RAM is required for both versions of BASIC. 
This means that user memory starts at hex 5200, resulting in 1 1.5K 
of user RAM in a 16K machine. 

Note: The memory which is completely untouched by both 
TRSDOS and DISK BASIC code begins at hex 7000. 

TRSDOS is comprised of a resident system and several overlays 
which are loaded from disk as the need arises (for example, to open 
or close a file). 

The system has a modular design. System entry-point vectors 
are in the lowest portion of the 4K RAM, followed by the interrupt 
handling, disk file handling, task scheduling and general purpose 
resident system routines. System buffers and overlays comprise the 
last portion of the 4K RAM requirement. 

Since all major system commands are actually loaded as needed 
from disk in the form of utilities (the "library commands" and the 
extended utility programs), the TRSDOS system facilities can easily 
be enhanced without affecting the RAM memory requirement. 



Disk Organization 



Each TRSDOS system diskette contains a TRSDOS system, a utility 
command library, a file directory, and system tables. 

The minimum system overhead amounts to one full track of directory 
information and a half track of TRSDOS bootstrap program and 
other information. This means that every TRSDOS diskette is self- 
loading, although it may or may not actually contain the TRSDOS 
system. This is done to prevent the Computer from attempting to 
bootstrap a diskette containing only user data files. 

The utility command library is optionally available on the diskette. 
Since the utility command programs are not always required, 
it will often be advantageous for multi-drive users to format 
diskettes for use in drives 1 through 3. Such "data diskettes" 
contain a minimum of system code, leaving more space for user 
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files. Maximum file size is limited only by the physical size of the 
diskette, since a file must be wholly contained on one diskette. 

Each diskette is single-sided and has 35 tracks of information. 
Each track contains 10 sectors of 256 bytes each. See Mini Disk 
Operation, "How a Diskette Works". 

Normally, data read/write operations may only be initiated at sector 
boundaries, and must consist of exactly 256 bytes. However, 
TRSDOS allows the user to have maximum flexibility with minimal 
effort by automatically blocking and de-blocking all file accesses 
to user-specified logical record lengths, even if this requires 
"spanning" of two sectors. 

The system disk file structure allows maximum use of disk file space 
by automatically segmenting files across a diskette in several small 
pieces. These pieces are correlated into one logically contiguous 
file by the system without your needing to know the physical file 
location. This structure eliminates time-consuming disk-packing 
operations. 

File Structure 

A TRSDOS file is composed of one or more segments of storage 
space. Each segment consists of from one to 32 physically 
contiguous granules of storage. A granule is the minimum 
allocatable unit of storage, and consists of five sectors (1.25K bytes). 
(See Figure below). 

Since a file is always lengthened by granules, a small amount of free 
storage is generally present at the end of every file. This free 
storage allows minor file additions to be made in space which is 
physically contiguous to the file. 

The effect is to decrease the amount of "thrashing" present in a file 
which has had frequent additions made. (A wholly sector-mapped 
system could not offer this benefit.) 

Every time a disk file is extended (either initialized or lengthened), 
extra granules may be allocated to that file, depending on the file's 
accumulated length, diskette space, saturation, etc. These extra 
granules, along with all granules after the one containing the file's 
EOF mark, are recovered and returned to the system when the file 
is closed. 
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A TRSDOS file 



RLE: 



SEGMENT: 



GRANULE: 



SECTOR: 



m^m^^^m^m^m^wmmt: 






SEGMENT 






SEGMENT 2 



GRANULE 



I 



GRANULE 2 



SECTOR X 



Jk 



SECTOR X+l 



GRANULE N 



SECTOR X+4 



BYTE 1 


BYTE 2 


BYTE 3 




BYTE 256 



LRN: Logical Record Number, used to specify an individual, 
user-defined logical record. Such a logical record is the 
smallest unit of information which can be addressed 
during disk input/output (a physical record is the unit 
which is actually read from or written to disk). 

File: A group of logical records; the largest unit of information 

which can be addressed by a TRSDOS command. 

Sector: A physical record, composed of 256 contiguous bytes. 

Granule: The minimum allocatable unit of storage for a particular 
file. 
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System Routines for Assembly-Language I/O 

This information is provided for customers who wish to write their 
own assembly level I/O routines. An explanation of the calling 
sequence and parameters for each necessary I/O routine is given. 
A knowledge of Z-80 machine code is assumed. 

The following notations are standard in this section: 

HL=> xxxx Registers HL contain the address of (point to) 
xxxx in machine format. (If address of 
xxxx=34B2H then the values in the registers are: 
H=34 ; L=B2 ) 

DE= > xxxx Registers DE contain the address of (point to) 
xxxx in machine format. (If address of 
xxxx=5AF1H then the values in the registers are: 
D=5A;E=F1) 

B= xx Register B contains the numeric value of xx in 

binary form. If xx=64 decimal, then B=40H. 

A= xx Register A contains the numeric value of xx in 

binary form. If .0;= 127 decimal, then A=7FH. 
Register A is used to return the TRSDOS error 
code for I/O calls. A complete list of error codes 
and their meanings appears at the end of this 
chapter. 

Z=OK Zero flag is set (OK) if successful return from the 

system routines. 

X'nnnn' Hard RAM address in nex notation (e.g., 402D is 

X'402D'). 

LRL Logical Record Lengtn. 1-255 bytes only. You 

can define records any length you wish up to 255 
bytes maximum. A length of zero is a special 
case for physical records only, and indicates 
the LRL=256 bytes. 

BUFFER 256 user designated bytes in RAM for TRSDOS 

to read sectors from or write sectors into. If 
LRL=0, this area is the responsibility of the user 
to manage before and after I/O. TRSDOS 
manages this area if LRL is between 1 and 255 
bytes. Do not alter this area when using logical 
record processing. 

UREC User record: the address of the contiguous 

RAM byte-string assigned by the user as his 
logical record area. Its length must be equal to 
LRL. It is a different area from BUFFER. 



6-5 



TRSDOS Technical Information 



DCB before OPEN and after CLOSE: 

The DCB is defined as 32 contiguous bytes of RAM designated by 
the user. Before OPEN and after CLOSE, it is a left justified, 
compressed (no spaces) ASCII string, as in a standard TRSDOS 
filespec: 

CONTENTS OF 32 - BYTE DCB 







8 


16 


24 32 


1 
F 

1 


1 1 1 1 
LENA 

1 1 1 I 


1 1 I 1 II 
M E / E X T 
1 1 ! 1 i 1 


I I I i i l i i i 
PASSWORD 

! I I I I I I I I 


I I I i I I I I I I 

I I I I 



Notes: /EXT, .PASSWORD, :D are optional. 
$ stands for a carriage return (X'OD'! 
£ stands for a blank (X'20'J 

Explanation of DCB while OPEN; 

Isb/msb is least significant byte followed by most significant byte in 
Z80 RAM format (i.e. addr=7CC8 in RAM is C8 7C). 

Addr. Len. Explanation 

— Reserved 

— Physical Buffer address (lsb/msb) 

— Offset to delimiter at end of current record 

— File drive number residence 

— Reserved 

— EOF offset of last delimiter in last physical record 

— LRL (logical record length) 

— NRN (next record no. — open sets=X'0000' — lsb/msb) 

— ERN (ending record no. — last in file — lsb/msb) 

— Reserved 

NRN Next Record Number defines which record is to be read or 
written by the next system call for READ or WRITE. It is 
automatically incremented by one after each system call. In order to 
process random files, use the POSN call to direct TRSDOS to the 
record you wish to transfer next. 

ERN Ending Record Number is the last record number currently 
in the file. It is put into the directory at CLOSE time, so if it is 
expected to be correct, the user must close his files after adding 
records to a file. This value may also be used to position to end of 
file so that new records may be added to the end of the file. To 
position to the end of file use a call to POSN with a record number 
of ERN+1 . POSN is described later. 



DCB+0 - 


3 


+3 - 


2 


+5 - 


1 


+6 - 


1 


+7 - 


1 


+8 - 


1 


+9 - 


1 


+10 - 


2 


+12 - 


2 


+ 14 - 


18 



6-6 



TRSDOS Technical Information 



Physical and Logical Records in TRSDOS 

A physical record is defined as one sector of disk. One sector of disk 
contains 256 user data bytes. The artificial term "granule" is 
defined to be 5 sectors of disk space. There are 2 granules on each 
of the 35 tracks on the disk. A granule is the least amount of space 
allocated by TRSDOS. For programming purposes, the physical 
records in a file are numbered from to N. The largest record 
number (N) in a file will then be five times the number of granules 
allocated minus one ((5*G)-1). All TRSDOS granule allocations 
are made as needed at the time of write, not when the file is 
created. 



Bytes 


Sectors 


Granules 


Tracks 


Disk 


256 


1 


_ . 


— 


— 


1280 


5 


1 


— 


— 


2560 


10 


2 


1 


— 


89600 


350 


70 


35 


1 



Disk Space Table : For each 5-1/4" Disk Drive 

A logical record is defined by the user of TRSDOS. It may be 
anywhere from 1 to 255 bytes in length. Once a file is opened with 
a specific LRL (Logical Record Length), the length is fixed until 
the file is closed. To change a file's LRL, you must CLOSE it and 
re-OPEN it with the new LRL. 



Each opening of the file sets a single, fixed record-length. 
TRSDOS will "block" logical records into (or from) one physical 
record for maximum space utilization on the disk. 

Blocking is putting more than one logical record into one physical 
record. For instance, four 64-byte logical records will fit into one 
256-byte physical record. A logical record may be broken into two 
parts by TRSDOS in order to fill the last portion of one physical 
record entirely before beginning to use the next physical record 
(i.e. records are spanned). This occurs when the physical record 
length is not an even multiple of the logical record length. 

If the user wishes to do his own blocking, he may specify a logical 
record length of bytes at the time of INIT/OPEN and must himself 
manage the contents of the physical record buffer area of 256 bytes. 
TRSDOS will not move a logical record for the user if LRL=0; in 
this particular case it will only read/write the physical record 
to/from the buffer. 
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Fundamental TRSDOS I/O Calls 

There are eight fundamental TRSDOS routines involved in handling 
file I/O. These are: 

INIT Creates a new file in the directory and opens it. 

No granule allocation is done. 
OPEN Opens an existing disk file. 

POSN Position for reading/writing a particular logical 

record. 
READ Reads one logical record into RAM from disk or 

from the physical buffer. 
WRITE Writes one logical record from RAM onto disk or 

into the physical buffer. 
VERF Writes then verifies by reading back and comparing 

to the original data written from RAM. Only 

pertains to LRL=0 physical records. 
CLOSE Closes an open file. 
KILL Closes a file and erases it from the directory. 

The detailed calling sequences and discussions for each of these routines 
follow. Note that all of these system calls use register F and do not 
restore its value before return. In order to properly apply this data, 
you should read through all of these descriptions and clear up all of 
the points that are not obvious to you by using other reference 
materials. If you are successful in doing this you will find that 
TRSDOS is a workable tool for your programming ideas. The jump 
vectors supplied here and the descriptions especially pertain to 
TRSDOS Version 2. 1 only. Future releases of TRSDOS may alter 
some of these descriptions or addresses. 

INIT (jump vector = X'4420') 

INIT is provided as an entry point to TRSDOS which will 
create a new file entry in the directory and open the DCB 
for this file. INIT scans the directory for the filespec name 
given in the DCB. If the filespec name is found, INIT 
simply opens the file for use. If the name is not found, 
a new file is created with the filespec name. 

entry: HL= >BUFFER (see beginning of this section for notation) 

DE= >DCB 

B=LRL 

CALL 4420H 
exit: Z=OK 

C carry flag is ON if a new file was created 

A=TRSDOS error code. (Error codes listed at end of 
this chapter) 
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OPEN (jump vector = X'4424') 

OPEN provides a way to open the DCB of a file which 
already exists in the directory. The DCB must contain 
the filespec of the file to be opened before entry to OPEN. 

entry: HL= > BUFFER 

DE=> DCB 

B = LRL 

CALL 4424H 
exit: Z=OK 

Z=0 if file does not exist. 

A=TRSDOS error code. 

POSN (jump vector = X'4442') 

POSN positions a file to read or write a randomly selected 
logical record. Since it deals with logical records, the 
proper computation is done to locate which physical 
record (s) contain the data. Following a POSN with a 
READ or WRITE will transfer the record to/from RAM. 

Note that positioning to logical record zero sets the file 
to read the first logical record in the file. To position to 
end of file in order to add new records onto the end, use 
the record number ERN+1 (see page 2). 

entry: DE= > DCB (must have been opened previously) 
BC= Logical record number to position for. 
CALL 4442H 

exit: Z=OK 

A=TRSDOS error code. 

READ (jump vector = X'4436') 

If LRL>0, READ transfers the logical record whose number is 
in the DCB as NRN (see page 2) into the RAM area 
addressed as UREC for the length LRL as defined at open 
time. The record comes from the RAM BUFFER defined 
at open time. If TRSDOS must read a new physical record 
to satisfy the request, it will do so. "Spanned" logical 
records will be re-assembled as necessary. READ auto- 
matically increments NRN by one in the DCB after the 
transfer is completed. INIT/OPEN sets NRN=X'0000' in 
order to read the first record with the first READ. 

If LRL=0, READ transfers one physical record into the RAM 
BUFFER, which was defined at open time, from the disk 
file. Registers HL are ignored. READ increments NRN 
as above. 
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entry: HL=> URECif LRL is not zero. Unused if LRL=0. 

DE= > DCB 

CALL 44364 
exit: Z=OK 

A=TRSDOS error code. (EOF=X' 1 C or X' 1 D') 
(see errors 28,29 for EOF or NRF) 

WRITE (jump vector = X'4439') 

IF LRL>0, WRITE transfers the one logical record from 

the RAM area addressed as UREC for the length LRL as 
defined at open time. The record goes into the RAM 
BUFFER which was defined at open time. If TRSDOS 
must write a physical record in order to satisfy the 
request, it will do so. "Spanning" will be handled by 
TRSDOS as necessary. At INIT/OPEN time the DCB 
value of NRN is set to X'0000' so that the first record will 
be written. After each logical record is transferred, the 
NRN value in the DCB will be incremented by one. 

IF LRL=0, WRITE transfers one physical record from the RAM 
BUFFER into the disk file using the NRN in the DCB. 
BUFFER IS DEFINED at INIT/OPEN time only. The DCB 
value NRN is updated as above, after the WRITE. 

entry: HL= > UREC if LRL is not zero. Unused if LRL= 

DE= > DCB 

CALL 4439H 
exit: Z=OK 

A=TRSDOS error code. 

YERF (jump vector = X'443C) 

The only difference between VERF and WRITE is that 
VERF writes one physical record to disk and then reads 
it back into a special TRSDOS RAM area not defined by 
the user. This special area and the original write buffer 
are then compared byte by byte to assure that the record 
was successfully written. 

entry: HL= > Same as WRITE above. 

DE=> DCB 

CALL 443CH 
exit: Z=OK 

A=TRSDOS error code. 
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CLOSE (jump vector = X'4428') 

CLOSE closes a file from the last processing done. It is 
very important to do a CLOSE on every file opened before 
the program ends. If you do not close a file, the directory 
entry for this file is incorrect if any new records have been 
written into the file. Other cases are not given here, but it is 
very important to TRSDOS that all of the "housekeeping" 
is complete for file management. 

entry: DE= > DCB 

CALL 4428H 
exit: Z=OK 

A=TRSDOS error code. 

KILL (jump vector = X'442C) 

KILL deletes the directory entry for an open file and then 
completes the close on the DCB. The disk space released 
by the old file is now re-useable for other purposes. 
Otherwise KILL is the same as CLOSE. 

entry: DE= > DCB 

CALL 442CH 
exit: Z=OK 

A=TRSDOS error code. 



Supplementary Information 

Other routines and addresses which may be of interest are defined 
here. Pay particular attention to the error routine. It does NOT 
perform error recovery. It displays TRSDOS error messages on the 
video display. 

(1) CALL402DH - Normal return to TRSDOS at program end. 

(2) X'43 1 8': address of the 64-byte buffer that contains the 

last TRSDOS command that was entered. Useful 
to decode special parameters entered when 
program was executed (run). 

(3) If HL = > 8-byte buffer, then: 

CALL 446DH returns the time of day into the 8 bytes 
in the ASCII format - HH:MM:SS 

CALL 4470H returns the date into the 8 bytes in the 
ASCII format - MM/DD/YY 

Binary forms of the time and date are located in TRSDOS 

RAM at these locations: 
X'4040' clock — real time clock heartbeat count. 25ms. 
X'4041' time — binary — 3 bytes — sec,min,hrs 
X'4044' date — binary — 3 bytes — yr, day, mon 
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(4) Printing TRSDOS error codes on the video display. 

CALL 4420H Example of system I/O call. Any call 
is ok. Zero flag not set means an error 
has occurred during the I/O attempt. 

JR Z,OKGO Ignore error message display if no 
error. 

OR 80H Optional for detailed error message. 

Register A already contains proper 
code for a single line message display. 

CALL 4409H Display error message on video screen. 

Optional user error recovery code goes here 
OKGO continue with program here — 



TRSDOS Error Codes — Returned in Register A 



decimal 
number 



prob. 
causes* 



error 
description 



00 — No error 

01 MD Parity error during header read 

02 D Seek error during read 

03 XK Lost data during read 

04 MD Parity error during read 

05 FMD Data record not found during read 

06 P Attempted to read system data record 

07 P Attempted to read system data record 

08 UP Device not available 

09 MD Parity error during header write 

10 D Seek error during write 

1 1 XC Lost data during write 

1 2 MD Parity error during write 

13 FMD Data record not found during write 

14 XD Write fault on disk drive 

1 5 UDX Write protected diskette 

16 PS Illegal logical file number (deb bad) 

17 MPDS Directory read error 

1 8 MPDS Directory write error 

19 UP Illegal file name (deb bad) 

20 MPDS GAT read error (Granule Allocation Table) 

2 1 MPDS GAT write error 

22 MPDS HIT read error (Hash Index Table) 

23 MPDS HIT write error 

24 UP File not in directory 

25 UP File access denied (protection violation) 



*See Explanation, next page. 
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decimal prob. error 

number causes description 



26 UP Directory space full (48 files max) 

27 UP Disk space full (70 granules max) 

28 P EOF encountered (End Of File) 

29 P NRF (No Record Found) out of file range 

30 UP Full directory. File can't be extended. 

3 1 UP Program not found 

32 UP Illegal drive number specified 

33 UP No device space available for new device 

34 MPUS Load file format error. Not a program. 

35 XCS Memory fault 

36 PUXC Attempted to load ROM memory 

37 P Illegal access attempted to protected file 

38 UP File has not been opened 
39-62 Not defined yet. Reserved 
63 P Unknown error code 

Explanation of probable cause codes: (column 2) 

C = TRS80 CPU fault P = User program error 

D = Disk drive fault S = TRSDOS fault. Reboot 

F = Diskette not formatted U = User procedural error 

M = Diskette media fault X = Expansion Interface fault 



6-13 



BASIC 











r > 

Radio /hack 

TRS-SO 

MICRO 

COMPUTER 

SYSTEM 











L 
A 



G 
U 
A 
G 

E 
S 



Contents of This Section 

Introduction 2 

Enhancements to LEVEL II 5 

Disk Features 26 

File Manipulation 28 

File Access 33 

Sequential Access Techniques 60 

Random Access Techniques 65 

DISK BASIC Error Messages 77 



Section 7 - Page 1 



DISK BASIC 



Introduction 



DISK BASIC is a set of enhancements to LEVEL II BASIC, plus 
features to allow disk input/output of BASIC programs and data. 
It is a memory image file stored on the TRSDOS software diskette 
with the name BASIC and extension /CMD. 

When DISK BASIC is loaded into RAM, it automatically takes 
control of the LEVEL II BASIC ROM program, using almost all of 
its routines and adding others. This is possible because LEVEL II 
was designed with upward compatibility built-in. (You can see this 
by examining the memory map for LEVEL II, in particular, hex 
addresses 37DE-37EC.) 

When loaded, DISK BASIC occupies approximately 5.8K bytes of 
RAM, beginning at hex address 5200 (decimal 20992). 

To load and execute DISK BASIC, first power-up the Disk Operating 
System (see System Operation), so that 

DOS READY 

is displayed. Now type: 

basic HUES 

TRSDOS will load BASIC into RAM, and BASIC will begin the 
"initialization dialog". This is a series of questions and answers 
which tell BASIC how to organize memory according to your needs. 

The first question is, 

HOW MANY FILES?. 

You repond with the maximum number of disk files that will be 
open (in use) at any one time - any number from zero to 15. 

(Every program or data set you store on the disk is referred to as a 
"file". In fact, everything on the disk, including system software, 
exists in the form of files.) 

The number you enter tells BASIC how many disk I/O buffers and 
data control blocks to create (for definitions, see Glossary). If n files 
are to be in use at once, then n buffers will be required. Each buffer 
will take 290 bytes from your available RAM (256 for the buffer plus 
34 for a data control block [DCB] ), so don't enter an unnecessarily 
large number. 

If you simply press I3^M3;1 without entering a number, BASIC 
will use a default value of 3 ; so you'll be able to have 3 file buffers 
in use at once. 
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Note: DISK BASIC automatically creates a buffer for loading, saving 
and merging BASIC programs. This buffer exists in RAM below 
any data file buffers you may request. It is always available for 
program I/O, regardless of how you answer the FILES? question. 

Suppose you're going to be using 2 files: 1 for inputting data, 
1 for outputting data. Then you might answer 2 to the FILES? 
question. However, if only 1 of these files will be open at once, then 
you really only need to reserve 1 file buffer/control block. 



Examples: 

HOW MRNY FILES? 8 MJH3H 

causes BASIC to set aside zero buffers for I/O to disk files. You 
won't be able to open files, but you will have the maximum amount 
of RAM for use by your program, 

HOW MANY FILES? 15 IdflHdsl 

tells BASIC to create 15 I/O buffers and control blocks; you will 
then be able to have 15 files open at once; however, this will reduce 
your available memory by 15*290 = 4350 bytes. 

HOW MANY FILES? 

tells BASIC to use a default of 3 for the number of files to be in use 
at once. 

After you answer the FILES question, BASIC will ask: 

MEMORY SIZE?_ 

You respond with the highest memory address (in decimal form) you 
want BASIC to use for storing and executing your BASIC programs. 
Addresses above the number you specify will then be protected 
from use by BASIC. 

Here's why you might want to protect memory: 

You can load machine-language programs or routines into high 
memory, and then access these routines from DISK BASIC via 
specially defined USRn functions, or via the SYSTEM command. 
These machine language routines may be loaded from tape using the 
SYSTEM command, LOADed in the DOS READY mode, or placed 
in memory one byte at a time using either DEBUG or BASIC POKE 
commands. If you do not reserve memory, such routines will be 
destroyed during execution of BASIC statements. 
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Example: 

MEMORY SIZE? 32880 HSHD 

causes BASIC to protect addresses above 32000. If you have 16K 
of RAM, this means that you'll have 32767-32000= 767 bytes 
protected for storing your machine language routines. 

If you don't want to reserve any memory, just press faMiazi 
without typing a number. 

MEMORY SIZE? HMM 

You will then have the maximum amount of RAM available for use 
by BASIC. 

Refer to the Memory Map for decimal addresses of the various 
TRS-80 memory configurations (16K, 32K, 48K). 

After you answer the MEMORY SIZE question, 

RADIO SHOCK DISK BASIC VERSION 1. 1 

READY 

">- 

will be displayed. You are now operating under DISK BASIC. 

To exit BASIC and return to the DOS READY mode, type: 

cmd-s" EHUD 

This results in a normal return to DOS — without re-initialization of 
the system. If you have a BASIC program in RAM, it will be lost, so 
be sure to save it on disk or tape before using CMD"S". 
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Enhancements to LEVEL II BASIC 

DISK BASIC adds many features to LEVEL II which are not disk- 
related. They are listed below along with abbreviated descriptions. 
Detailed descriptions follow in alphabetical order. 

&H Hexadecimal-constant prefix 

&0 Octal-constant prefix 

CMD"D" Enable and load the real-time debugging program 

CMD"R" Enable interrupts (start real-time clock) 

CMD"S" Normal return to TRSDOS (jump to EXIT routine) 

CMD'T" Disable interrupts (turn off real-time clock) 

DEF FN Define an implicit BASIC-statement function 

DEF USR Define the entry point for an external 

machine-language routine 

INSTR Instring function; find substring in target string 

LINE INPUT Input a line from keyboard 

MID$= Replace portion of target string (used on left 

of equals sign) 

TIMES Get time and date from real-time clock 

USRft Call external routine (n=0, 1,2,... ,9) 



Cassette Operations 

Before any BASIC cassette input or output operation, you must 
disable interrupts with the CMD'T" command. This is because such 
cassette operations are timing-sensitive and cannot work if they are 
being interrupted every 25 milliseconds. When the cassette operation 
is complete, you can re-enable interrupts by executing the statement 
CMD"R". 

CLOAD allows no filename in DISK BASIC. Tnerefore you cannot 
use such a filename to sort through several tape files. CLOAD will 
always load the first file encountered on the tape. CSAVE, however, 
still requires the filename. This way, programs CSAVEd under 
DISK BASIC can be loaded and sorted through via the LEVEL II 
CLOAD"/z/e«ame" command. 

CLOAD? (CLOAD-verify), used in LEVEL II to compare a BASIC 
program in RAM with one on tape, will not work with programs 
saved on tape under LEVEL II. It will work with programs saved 
under DISK BASIC. 
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Error Messages 

When an error occurs, DISK BASIC "spells out" the full error 
message, not just the abbreviation. This saves you from having 
to look it up. 

Example: 



error<i4) mma 

DISK BASIC responds with: 

OUT OF STRING SPACE 

Note: The ERROR function, used to simulate error conditions, will 
work only with non-disk error codes. 

&H and &O (hex and octal constants) 

Often it is convenient to use hex (base 16) or octal (base 8) 
constants rather than their decimal counterparts. For example, 
memory addresses and byte values are easier to manipulate in hex 
form. &H and &0 let you introduce such constants into your 
program. 

&H and &O are used as prefixes for the numerals that immediately 
follow them: 



&Hdddd 

where dddd 



&Oddddd 

where ddddd 



is a 1 to 4 digit sequence composed of 
hexadecimal numerals 0, 1 , . . . 9,A,B, . . . ,F 

is a sequence of octal numerals 0, 1 , . . .,7. 
and &Oddddd< = 1 77777 decimal. 
Note: The O can be omitted from the 
prefix &0. Therefore &Oddddd=&ddddd. 



The constants always represent signed integers. 
Therefore any hex number greater than &H7FFF, or any octal 
number greater than &077777, will be interpreted as a negative 
quantity. The following table illustrates this: 



Octal 



Hex 



Decimal 



&1 


&H1 


1 


&2 


&H2 


2 


&77777 


&H7FFF 


32767 


& 100000 


&H8000 


-32768 


&1 00001 


&H8001 


-32767 


&100002 


&H8002 


-32766 


&177776 


&HFFFE 


-2 


&177777 


&HFFFF 


-1 



■a 
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Hex and octal constants cannot be typed in as responses to an 
INPUT prompt or be contained in a DATA statement. Often the 
hex or octal constant must be enclosed in parentheses to prevent a 
syntax error from occurring. 



Examples: 



PRINT &H526& 4051006 



prints the decimal equivalent of the two constants (both equal 
20992). 

POKE &H3C0&42 

puts decimal 42 (ASCII code for an asterisk) into video memory 
address hex 3 COO. 

100 FOR I=<&H2C00> TO (&H2FFF) STEP <&H40) 
200 IF fl=<&H37E8) THEN R=fl+1 

300 POKE FTC, (XX AND &HFF) 

Masks the most significant byte of X% and POKEs the result into 
location A%. 

CMD"D" (execute DEBUG program) 



CMD"D' 



Executing this statement causes the TRSDOS debugging program to 
load and execute. (See TRSDOS Commands, DEBUG.) Your BASIC 
program is unaffected, since DEBUG loads below DISK BASIC. 

To return to BASIC without re-initialization, type 

The READY message will appear and you can continue in BASIC. 

Once CMD"D" has been executed, DE BUG will take over whenever 
you press the BREAK key. Pressing G [jJJjj^O will return you to 
BASIC again. Type CONT to continue any program that was 
executing when you typed BREAK. 

To return from DEBUG to the BASIC initialization sequence, type 
G5200 HittH;! . You will lose any BASIC program text or 
variable values. 
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Examples: 



106 -" PROGRAM: DEBUG 

118 ' EXAMPLE OF EXECUTION WITH DEBUG WITHIN A PROGRAM 

128 ' 

130 CLS: PRINT TAEK15X; "DEBUG EXAMPLE": PRINT 

148 PRINT"ENTERING DEBUG" 

158 FOR 1=1 TO 506: NEXT I 'DELAY A WHILE 

168 - 

170 ' *** ENTER DEBUGGING PACKAGE *** 

ISO '" 

198 CMD"D" 

200 ' 

210 ' *** RETURN HERE WHEN "G" ENTER TVPED IN DEBUG *** 

220 - 

230 CLS: PRINT: PRINT "YOU HAVE RETURNED FROM DEBUG" 

240 END 




run ranm 




DEBUG EXAMPLE 



ENTERING DEBUG 
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flF = 44 


42 


„ 2 _ 


— -N- 




















BC = 69 


81 


=> 


57 49 


54 


48 


49 


4E 


20 


41 


28 


58 52 


4F 47 52 41 4D 


DE = 69 


B8 


=> 


44 22 


00 


C3 


69 


C8 


00 


3H 


93 


FB 00 


FD 69 D2 88 3fl 


HL = 48 


B? 


~y 


69 55 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


88 88 


00 60 08 88 54 


AF"" = FF 


FF 


SZ1H1PNC 




















BC"= 4D 


BE 


~_> 


51 51 


CD 


FC 


51 


7E 


cUS 


18 


EC 


82 82 


80 4E 83 32 E7 


DE' = 01 


@7 


=f> 


4D 4F 


■Jc, 


59 


28 


cr-;- 
•J _> 


49 


5R 


45 


60 52 


41 44 49 4F 20 


HL-"= 40 


88 


—.••' 


F2 51 


06 


10 


CD 


65 


51 


3R 


5D 


48 FE 


41 28 13 CD F2 


IK = 49 


15 


^;_> 


81 E3 


83 


80 


88 


08 


4B 


49 


87 


58 84 


31 3E 88 44 4F 


IV = FF 


FF 


— .••* 


FF F3 


RF 


C3 


74 


06 


C3 


00 


48 


C3 88 


48 El E3 C3 9F 


SP = BD 


6C 


~J> 


BR 69 


IE 


ID 


08 


00 


84 


04 


28 


88 88 


88 88 80 00 08 


PC = 5? 


88 


_*•. 

-.••• 


El C9 


3R 


29 


5B 


F6 


C0 


CD 


89 


44 El 


C9 D7 E5 3E 11 


1819 


~y 


28 10 


FE 


44 


28 


8C 


FE 


38 


28 


F8 FE 


2C 28 EC FE 2E 


1029 


~y 


28 83 


2B 


36 


38 


7B 


E6 


18 


28 


83 2B 


36 24 7B E6 84 


1038 


=> 


C0 2B 


70 


C9 


32 


D8 


40 


21 


30 


41 36 


28 C9 FE 85 E5 


G E3E2 1840 


=> 


DE 88 


17 


57 


14 


CD 


01 


12 


81 


80 83 


82 FA 57 18 14 




VOU HAVE RETURNED FROM DEBUG 
RERDV 
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CMD"R" (start clock [enable interrupts]) 



CMD"R" 



Execute this command immediately after completion of a cassette 
input/output operation to re-start the real-time clock. See CMD'T". 

CMD"S" (return to TRSDOS) 



CMD"S" 



Execute this command to initiate a normal return to the Operating 
System command mode. This will not re-initialize the system, but 
merely get you out of BASIC. 

Be sure to save any BASIC program on disk or tape before using 
CMD"S", as your resident BASIC program will be lost. 

CMD"T" (stop clock [disable interrupts]) 



CMD'T" 



You must execute this command immediately before any BASIC 
tape input/output operation. Such operations are timing sensitive 
and cannot allow the interrupt-driven tasks (such as the real-time 
clock, TRACE, and CLOCK-display) to "steal" time. 

Here are the commands which must be preceded by execution of 
CMD"T": 

CLOAD CLOAD? 

INPUT#-1 CSAVE 

INPUT#-2 PRINT#-1 

SYSTEM PRINT #-2 

After completion of these operations, you can execute a CMD"R" 
to re-enable interrupts. 

Example: 

10 OPEN'TVl, "TEST/BBS" 
26- CMD"T" : INPUT**!, fi, B, C 
26 CMD"R" 
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Note: After CMD"D", you can use CMD'T" to prevent BASIC from 
transferring control to the DEBUG program when BREAK is pressed. 



DEF FN (define function) 



DEF FN varl{var2[,var . . . ] ) = exp 




where 


varl 


will be the name of the function, 
valid LEVEL II variable name 


and is any 




var2 


and subsequent var-items are 








used in defining what the function does 




exp 


is an expression usually involving 


the variable(s) 






passed on the left of the equals si 


gn 



This statement lets you create your own implicit functions. That 
is, you only have to call it by name and the implicit function you 
defined will automatically be performed. Once a function has been 
defined with the DEF FN statement, you can call it simply by 
referencing the function name prefixed by FN. You can use it 
exactly as you'd use one of the intrinsic functions, e.g., SIN, ABS, 
STRINGS. 

The type of variable used to name the function determines what type 
of value the function will return. For example, if the function name 
has the single-precision attribute, then that function will return a 
single-precision value — regardless of the precision of the arguments. 

Examples: 

DEFFNFI$<TITLE*, QRflPHICS^>=STRING*CLEN(TITLE*), GRAPH I CSX) 

The function A$ will require two arguments - one integer, one 
string; and it will return a string value. 

DEFFNRC!<fl>=l/<fi*fi> 

The function RC! requires one argument, and returns a single- 
precision value, regardless of the precision of the argument. 

The particular variable names you use as arguments in the DEF FN 
statement are not assigned to the function; when you call the 
function later, any valid variable name of the same type can be 
used. Furthermore, using a variable as an argument in a DEF FN 
statement has no effect on the value of that variable. 

The function must be defined with at least one argument — even if 
this argument is not actually used to pass a value to the function. 
For example: 

DEF FNR<fl)=RND(0) 
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Examples: 

19 DEFFNMLKfi, B)=fi*B 

2@ INPUT "ENTER ARGUMENTS"; X, V 

36 PRINT "PRODUCT IS"; FNMLT<X,Y> 

Notice that FNMLT is defined with arguments A,B, but that when 
the function is called in line 30, variables X and Y are used. Any 
two valid variable names can be used to pass values to the function. 



DEF FNRR<A, B>=fi+INT<B*RND03>} 



DEF FNLS* < fi* ) =LEFT* ( H$, 8 ) 



DEF FNX# < A#, B# ) = ( m-B% ) * < R#-B# > 



Returns a random 
number between 
A and B. 
Returns first 8 
characters of string 
argument 
Returns double- 
precision value of "the 
square of the 
difference" 



100 ■"' PROGRAM: STRING 

110 ' EXAMPLE OF fi STRING DEFFN FUNCTION 

120 ' 

13:0 ' ******* FUNCTION TO CONCATENATE STRINGS ******* 

135 "' 

140 DEF FNADD* <A$, B$) = fit- + " " + Bf- 

150 CLS: PRINT TAB < 15); "STRING DEFFN EXAMPLE" 

160 PRINT: F*= nii : INPUT "ENTER FIRST NAME"; F$ 

165 IF F*="" THEN END 

170 INPUT "ENTER LAST NAME"; LI- 

180 -' 

•130 - ******* RDD FI- TO L$ WITH 1 BLANK IN BETWEEN ******* 

200 -' 

210 Z$ = FNADD$ <F$, L$> 

220 PRINT TAB<6); "FULL NAME: "; 2$ 

230 GOTO 160 



RUN [121051 



STRING DEFFN EXAMPLE 



ENTER FIRST NAME? JOH N UMM 
ENTER LAST NAME? DOEH2H13 
FULL NAME: JOHN DOE 
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100 
110 
126 
130 

135 
140 
150 

160 
170 
180 
190 

200 

210 
220 
230 
240 
250 
260 
270 
280 
290 

300 

310 
320 
330 
340 
350 
360 
370 



PROGRAM: MINMAX 

•' EXAMFLE OF DEFFN FEATURE 
.•• 

- ******* DEFINE MIN AND MAX FUNCTIONS ******* 

DEF FNMIN (A, B) = (A + B - ABS (A - B)> / 2 

DEF FNMAX (A, B) = (A + B + ABS (A - B)> / 2 
.•■ 

•- ******* READ 1ST VALUE - CALL IT THE MIN AND MAX ***** 
MN IS CURRENT MINIMUM VALUE 

MX IS CURRENT MAXIMUM VALUE 

.■• 

READ MN: MX = MN 

< ******* GET NEXT VALUE AND FIND NEW M IN/MAX ******** 

READ V: IF V = 99999 THEN 320 -"V-99999 MEANS ALL DONE 

MN = FNMIN (MN, V) 'GET NEW MINIMUM 

MX = FNMAX (MX, V> 'GET NEW MAXIMUM 
GOTO 250 

■•" ******** PRINT RESULTS ******* 

PRINT "MINIMUM VALUE =", MN 

PRINT "MAXIMUM VALUE = H , MX 

.•• 

•- ******* DATA FOLLOWS - LAST VALUE MUST BE 99999 ******* 
.•• 

DATA 1. 2, 2, 3, 4. 7, 5. 332, 0. 314, 6, 7, 8. 3, 9. 57, 99999 



■mm Hsmi 

MINIMUM VALUE = . 314 

MAXIMUM VALUE = 9. 57 

READY 

>37B Dfftft - jb 9, & 8, 1. 7, 2, 6, 3, 5, 4, 99999 [IMS 

>run EMUS 

MINIMUM VALUE = -i 
MAXIMUM VALUE = 9 
READY 
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UrLr Ui3lv 

(define entry address for USR routine) 



DE¥\JSRn=nmexp 

where n 

nmexp 


equals one of the digits 0, 1 , ... ,9 ; 
if n is omitted, is assumed 
specifies the entry address to a 
machine-language routine. 



This statement lets you define the entry points for up to 10 machine- 
language routines. (In LEVEL II, where only one USR routine is 
available, the entry point address is POKEd into RAM.) 

Example: 

106 DEFUSR3=&H?D00 

Assigns the entry point 7D00 hex, 32000 decimal, to the USR3 call. 
When your program calls USR3, control will branch to your sub- 
routine beginning at hex 7D00. . 

Here are three ways to get a machine language program into RAM so 
that it can be accessed via a USRn call: 

• 1 ) Use the TRS-80 Editor Assembler, Radio Shack Catalog 

Number 26-2002, to convert the source code into an object 
file on tape; then load the tape under the SYSTEM 
command (use MEMORY SIZE to protect the code from 
destruction by BASIC). 

2) Use the TRSDOS DEBUG program to type in the machine- 
code routine (then DUMP it to disk for safe-keeping); 

call DISK BASIC and answer MEMORY SIZE so as to 
protect the routine. 

3) Have your DISK BASIC routine POKE the routine (decimal 
values for each byte) into high RAM. MEMORY SIZE 
should be set during initialization to protect the area you 
will POKE into. 

See USRn. 
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INSTR (string search function) 



INSTR([«,] expl$,exp2$) 



where n 



expl$ 
exp2$ 



specifies a position in expl $ where the 
search is to begin; if n is not supplied, 
1 is assumed. (Position 1 is defined as 
the first character in the string.) 
is the string to be searched 
is the substring you want to search for 



This function lets you search through a string to see if it contains 
another string. If it does, INSTR returns the starting position of the 
substring in the target string; otherwise zero is returned. Note that 
the entire substring must be contained in the search string, or zero 
is returned. Also note that INSTR only finds the first occurrence of 
a substring, starting at the position you specify. 



Examples (let A$="ABCDEFG"): 
Expression 



Result 



INSTR(A$,"BCD") 

INSTR(A$,"12") 

INSTR(A$,"ABCDEFGH") 

INSTR(3,"1232123","12") 



See the EDIT program under MID$= for a sample use of INSTR. 
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LINE INPUT (input a line from keyboard) 



LINE INPVTV'prompt"] \var$ 

where prompt is a prompting message 

var$ is the name that will be assigned to the line you 
type in 



LINE INPUT (or LINEINPUT - the space is optional) is similar to 
INPUT, except: 

• When the statement is executed, and the Computer is waiting for 
keyboard input, no question mark is displayed 

• Each LINE INPUT statement can assign a value to just one variable 

• Commas and quotes will be accepted as part of the string input 

• Leading blanks are not ignored — they become part of var$ 

• The only way to terminate the string input is to press idfliiasi 

LINE INPUT is a convenient way to input string data without having 
to worrv about accidental entry of delimiters — because only the 
la^ftid:! key serves as a delimiter. If you want anyone to be able to 
input information to a program without special instructions, use 
LINE INPUT and then analyze the resultant string. 

Some situations require that you input commas, quotes and leading 
blanks as part of the data. LINE INPUT serves well in such cases. 

Examples: 

LINE INPUT A* 
Input A$ without displaying any prompt. 

LINE INPUT"LAST NAME, FIRST NfiME? M ;N$ 

Displays a prompt message and inputs data. Commas will not termi- 
nate the input string. 

Try the following program to get the idea of LINE INPUT. 

108 -' PROGRAM: LN INPUT 

110 •- EXAMPLE OF LINEINPUT STATEMENT 

120 ' 

130 CLEAR 300: CLS 

140 PRINT TAEK15); "LINE INPUT STATEMENT": PRINT 

150 PRINT: PRINT "*** ENTER TEXT ***« 

151 •'■ 

152 ' *** GET STRING, THEN PRINT IT *** 

153 ' 

155 A*= M " 'SET A$ TO NULL STRING 
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169 LINE INPUT "==> ".; A* 

165 IF A*= ,,H THEN END 'IF STILL NULL STRING, STOP! 

176 PRINT fit- 



189 GOTO 155 




LINE INPUT STATEMENT 



*** ENTER TEXT *** 

--"> ■ ■E^Hf-IJ: "TEXT 

THIS TEXT HAS EMBEDDED LINE FEEDS -AND TABS 

IN IT. LINEINPUT ALSO ALLOWS DELIMITER <, :;"' ETO.HBEa 

EXAMPLE TEXT 
THIS TEXT HAS EMBEDDED LINE FEEDS AND TABS 
IN IT. LINE INPUT ALSO ALLOWS DELIMITER <, :; •" ETC). 

— — _■• i3Uyj3Al 

REflDV 




MID$= (replace portion of string) 



MlD$(var$,nl[,n2]) = exp$ 




where var$ names the string to be changed 




nl specifies the starting position for the 




replacement 




n2 specifies how many characters are to be 




replaced; if n2 is omitted, LEN(<?xp$) or 




LEN(var$)-nl+l is used, whichever is 




smaller. 





This statement lets you replace any part of a string with a specified 
substring, giving you a. powerful string-editing capability. 

Note that the length of the target string (var$) is never changed by 
the MID$= statement. If the replacement string, exp$, is too long 
to fit in the specified portion of var$, then the extra characters at 
the right of exp$ are ignored. 
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However, if you specify the number of characters to be replaced, 
and this number is larger than the replacement string, then the 
length of the replacement string overrides the length you specified. 

A$="ABCDEFG" at the beginning of each example below: 

Ex. # Expression Resultant A$ 

1 MID$(A$,3,4)="12345" AB1234G 

2 MID$(A$,1,2)="" ABCDEFG 

3 MID$(A$,5)="12345" ABCD123 

4 MID$(A$,5)="01" ABCD01G 

5 MID$(A$,1,3)="***" ***DEFG 

In example 2, the specified replacement length exceeds the length 
of the replacement string (which is zero); therefore the replacement- 
string length is used. In effect, no characters are replaced. 

Sample program: EDIT 

This program accepts an initial string, asks for a replacement position 
and a replacement string. Then it performs the MID$= replacement 
and prints the new string. Type in a position equal to zero to stop 
the program. 

160 " PROGRAM: EDIT 

110 " EXAMPLE OF INSTR FUNCTION FOR TEXT ED ITT I NG 

115 •" 

120 CLEAR 806: CLS 

138 PRINT TAB<15>; " STRING-FUNCTION EDITOR" 

135 •- 

14@ - ******* GET INITIAL TEXT ******* 

145 •- 

150 PRINT: PRINT "ENTER INITIAL TEXT STRING" 

160 S$="": LINE INPUT S$: IF S*="" THEN END 

165 •' 

170 •- ******* GET TARGET & REPLACEMENT STRINGS ******* 

1?5 -' 

180 T$= ,,H : PRINT: LINE INPUT" TARGET STRING ".; T* 

185 IF T*="" THEN END 

190 LINE INPUT "REPLACEMENT STRING "; R$ 

195 IF LEN<T*X>LEN<R$>THEN PR I NT "CAN'T CHANGE STRING LENGTH" 

GOTO 180 
200 •- ******* MAKE REPLACEMENT <S) AND PRINT NEW STRING ***** 
210 1=1 -VARIABLE I POSITIONS TO BEGINNING POINT OF SEARCH 
220 I=INSTR(I, S$, T$): IF 1=0 THEN 150 '1=0 IF NOT FOUND 
230 MID*<S$, I)=R$ -MAKE REPLACEMENT 
240 PRINT "POSITION - "; I: PRINT S$ 
250 I=I+LEN<R*>: GOTO 220 -ADVANCE POSITION 
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STR I NG -FUNCT I ON ED I TOR 

ENTER INITIAL TEXT STRING 

CHRNGE "DISC" TO "DISK" EACH TIHE IT OCCURS. . 




TARGET STRING DISC LaiJtUJ 
REPLACEMENT STRING DISK UftiiA 
POSITION - 9 

CHANGE "DISK" TO "DISK" EACH TIME IT OCCURS. 
POSITION - 48 
CHANGE "DISK" TO "DISK" EACH TIME IT OCCURS. 



ENTER INITIAL TEXT STRING E2EE3 
READV 



TIME$ (get value of Real-Time Clock) 




TIMES 



TIMES is a function with no arguments - when executed, it returns 
a string-value composed of the date and time currently stored in the 
Real-Time Clock memory area. The string is always 17 characters 
long and has the following format: 

MM/DD/YY#HH:MM:SS (month/day /year hr:min:sec) 

The hour appears in 24-hour form, e.g., 1:30 PM appears as 13:30. 

To set the time and date, get into the DOS READY mode and use 
the TRSDOS commands, TIME and DATE, as follows (assume it's 
3:30 PM on January 1, 1979): 

TIME 15:30:00 R^FH 
DATE 01/01/79 RTfFffl 

Or, you can set the time and date under DISK BASIC, by POKEing 
the time and date values into the appropriate addresses (see 
CLOCK, TRSDOS Library Commands). 

TIMES can be printed or used internally by your program in dedicated 
applications. 



7-19 



DSSK BASIC 



Examples: 



1606 IF LEFT*(TIME*,15>="0?/04/?9 26:00"THEN 2606 

1010 GOTO 1006 

2000 REM. . . IT'S 8PM ON JULY 4TH, 1379 
2010 REM. . . STflRT FIREWORKS DISPLAY 



The following program, CLOCK, will display the time and date until 
you press the @-key. 

100 - PROGRAM: CLOCK 

110 -' EKAMPLE OF TIME* 

120 '■ 

130 CLS: PRINT CHR* (23) 'GET INTO 32 CHARACTER MODE 

146 ' 

150 - ******* print TIME AND DATE ******* 

ISO "" 

170 PRINT e 264, "THE TRS-8© TIME IS".; 

180 PRINT @ 458, "DATE: "; LEFT* (TIME*. 8); 

196 PRINT @ 586, "TIME: '*.; RIGHT* (TIME*, 8).; 

200 ' 

210 ' ******* STOP IF "@" KEY IS DEPRESSED ******* 

220 ' 

236 A*=INKEY*: IF A* = "§" THEN END ELSE 180 



USRn (call to user's external subroutine) 



\JSR[n] (nmexp) 



where n specifies one of ten available USR calls, 
7-2=0, 1 ,2, ... ,9. If n is omitted, zero is 
assumed. 
nmexp is in the range < -32768 +32767 > and 
is passed as an integer argument to the 
routine 



These functions (USRO through USR9) transfer control to machine- 
language routines previously defined with DEFUSRji statements. 

When a USR call is encountered in a statement, control goes to the 
address specified in the DEFUSR/? statement. This address specifies 
the entry point to your machine-language routine. A RET or JP 
0A9A instruction in the routine returns control to the USR call in 
your BASIC program. 
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Note: If you call a USRn routine before defining the routine entry 
point with DEFUSR/?, an ILLEGAL FUNCTION CALL error will 
occur. 



You can pass one argument and retrieve one output value directly 
via the USR argument; or you can pass and retrieve arguments 
indirectly via POKE and PEEK statements. 

Example: 

IS DEFUSR1=&H7D00 

26 REM. . . MORE PROGRRH LINES HERE 

100 fMJSRKX) 



The effect of this sequence is to: 

1) Define USR1 as a routine with an entry point at hex 7D00 
(line 10) 

2) Transfer control to the routine; the value X can be passed 
to the routine if the routine makes the CALL described 
below (line 100) 

3) When the routine returns to BASIC, the variable A may 
contain the value passed back from the routine (if your 
routine makes the JUMP described below); otherwise A 
will be assigned the value of X (line 100). 



Passing arguments to and from USR routines 

There are several ways to pass arguments back and forth between 
your BASIC main program and your USR routines: the two major 
ways are listed below. 

1. POKE the argument(s) into fixed RAM locations. The 
machine-language routine can then access these values and 
place results in other RAM locations. When the routine 
returns control to BASIC, your program can PEEK into 
these addresses to pick up the "output" values. This is 
the only way to pass two or more arguments back and 
forth. 

2. Pass one argument to the routine as the argument in the 
USRn call, then use special ROM calls to access this 
argument and return a value to BASIC. This method is 
limited to sending one argument and returning one value 

(both are integers). 
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ROM Calls 

CALL OA7FH 

JP 0A9AH 



Puts the USR argument into the HL register pair; 
H contains msb, L contains lsb. This CALL should 
be the first instruction in your USR routine. 

Use this JUMP to return to BASIC; the integer in 
HL becomes the output of the USR call. If you 
don't care about returning HL, then execute a 
simple RETurn instruction instead of this JUMP. 



Examples: 



Listed below is an assembled machine-language routine that will 
accept the argument from the USR call in BASIC, left-shift it one 
position, and return the result to BASIC. 







00100 


.; 














08110 


i SHIFT 


FUNCTION 










00120 


i 














00130 


.; 


MACHINE 


CODE PROGRAM TO 1 


LEFT SHIFT 






£i8140 


.; 


RN ARGUMENT SENT FROM 


BR 


SIC AND RETURN 






00150 


.; 


THE RES 


ULT BACK TO BR! 


SIC 








80160 


.; 










7D00 




00170 
00180 


J 


ORG 


7D88H 










00190 


; EQUATES RND ENTRV POINTS 










00200 


i 










8A7F 




00210 


GETARG 


EQU 


8R7FH 




;GET ARGUMENT FROM BASIC 


8A9A 




00220 
00230 


PUTRNS 


EQU 


8R9RH 




; RETURN ANSWER TO BASIC 


7D00 


CD7F8A 


00240 


SHIFT 


CALL 


GETflRG 




;GET NUMBER FROM BASIC 


7D83 


CB15 


00250 




RL 


L 




; SHIFT L 


7D05 


CB14 


88260 




RL 


H 




; SHIFT H - ANSWER IN HL 


7D07 


C39A8A 


00270 
00280 




JP 


PUTRNS 




i RETURN TO BASIC W ANSWER 


7D00 




08298 




END 


SHIFT 







The following program includes the decimal code for the SHIFT 
routine. The code is POKEd into RAM and then accessed as a USR 
routine. RUN the program; to stop, enter a value of zero. 

Note: The following two BASIC programs require that you reserve 
memory addresses above 31999 for the USR Code. (Answer MEMORY 
SIZE? with 31999.) 
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100 
110 

120 
130 
140 
150 
160 
178 
180 
190 

200 

210 

220 
230 
240 
250 
260 
270 

290 

300 

310 
320 
330 
340 



PROGRAM: SHIFT 
•' MRCHINE LANGUAGE USER FUCTION TO LEFT SHIFT 

- ******* MACHINE CODE AT 7D00 HEX ******* 

DEFUSR5 = &H7D00 

•- ******* POKE USER PROGRAM INTO MEMORY ******* 

FOR X = 32000 TO 32009 '7D00 HEX EQUALS 32000 DECIMAL 

READ A 

POKE X,A 
NEXT X 

•- ******* GET VALUE FROM USER ******* 

CLS: PRINT TAEK15); "USR5 LEFT-SHIFT FUNCTION" 

PRINT: INPUT "ENTER INTEGER VALUE".: V 

IF V=0 THEN END 

PRINT "LEFT SHIFTED VALUE = ".; TAEK32); USR5<V) 

GOTO 270 

- ******* DATA IS DEM1CAL CODE FOR HEX PROGRAM ******* 
DATA 205, 127, 10, 203, 21, 203, 20, 195, 154, 10 




USR5 LEFT-SHIFT FUNCTION 



ENTER INTEGER VALUE? 7 035110 
LEFT SHIFTED VALUE = 



14 



ENTER INTEGER VALUE? -7 L3UUil 
LEFT SHIFTED VALUE = -13 



ENTER INTEGER VALUE? 3276? HZEED 
LEFT SHIFTED VALUE = -2 



ENTER INTEGER VALUE? LHillHi] 
READY 
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Listed below is an assembled program to white out the display (an 
"inverse" CLEAR key!). 



7D88 



3C88 
88BF 
83FF 



7D88 21883C 
7D83 36BF 
7D85 11813C 
7D88 81FF83 
7D8B EDB8 

7D8D C9 
7D08 



80100 
00110 

00128 
88130 

00140 

88158 
88168 
88178 
88188 
88198 
88288 
88218 
88228 
00230 
00248 
00258 
88268 
88278 
88288 
88298 
88388 



.; 2fiP OUT SCREEN USR FUNCTION 



ORG 

.; EQURTES 

VIDEO EQU 
WHITE EQU 
COUNT EQU 



7D88H 



3C88H 

8BFH 

3FFH 



.; START OF VIDEO RAM 
.;fil_L WHITE GRAPHICS BVTE 
.; NUMBER OF BVTES TO MOVE 



.; PROGRAM CHAIN MOVES X'BF' INTO ALL OF VIDEO RAM 



ZAP 



LD 


HL, VIDEO 


;SOURE ADDRESS 


LD 


<HL>, WHITE 


.;PUT OUT 1ST BVTE 


LD 


DE..VIDEO+1 


.; DESTINATION ADDRESS 


LD 


BC, COUNT 


> NUMBER OF ITERATIONS 


LDIR 




;DO IT TO IT!!! 


RET 




j RETURN TO BASIC 


END 


ZAP 





This routine can be POKEd into RAM and accessed as a USR 
routine, as follows. 
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109 •- PROGRAM: USR1 

110 -' EXAMPLE OF A USER MACHINE LANGUAGE FUNCTION 

115 ' DEPRESS THE '<?' KEV WHILE NUMBERS ARE PRINTING TO STOP 

128 ' 

130 - ******* F'OKE MACHINE PROGRAM INTO MEMORY ******* 

148 ' 

156 DEFUSR1 = .&H7D0O 

160 FOR X = 32O00 TO 32013 '7D0O HEX EQUAL 32000 DECIMAL 

170 READ A 

180 POKE X, A 

190 NEXT X 

192 ' 

194 ' ******* CLEAR SCREEN & PRINT NUMBERS 1 THRU 100 ******* 

196 •' 

200 CLS 

205 PRINT TAB<15); M WHITE-OUT USER ROUTINE": PRINT 

210 FOR X = 1 TO 100 

220 PRINT X; 

225 A* = INKEY*: IF A* = "§" THEN END 

230 NEXT X 

240 •' 

250 ' ******* JUMP TO WHITE-OUT SUBROUTINE ******* 

260 ' 

270 X = USR1 (0) 

280 FOR X = 1 TO 1000: NEXT X "DELAY LOOP 

290 GOTO 200 

300 ' 

310 ' ******* DATA IS DEMICAL CODE FOR HEX PROGRAM ******* 

320 ' 

330 DATA 33, O, 60, 54, 255, 17, 1, 60, 1, 255, 3, 237, 176, 201 



RUN the program. An equivalent BASIC white out routine takes 
a long time by comparison! 
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Disk-Related Features 



Programs and data are stored as "files'' under TRSDOS. 
Each program or data-set on the disk has its own, distinct 
file specification - which includes a name plus identifying 

Before attempting any disk input/output - including 
loading and saving BASIC programs, refer to the TRSDOS 
Overview. Also, review the Notation Conventions 
described under General Information. That's the only 
way to be sure you understand the statement syntax 



DISK BASIC provides a powerful set of commands, statements and 
functions relating to disk I/O under TRSDOS. These fall into two 
categories: 

1 . File manipulation: dealing with files as units, rather than 
with the distinct records the files contain. 

2. File access: preparing data files for I/O; reading and 
writing to the files. 

Commands discussed under "File Manipulation": 



KILL 


delete a program or data file 




from the disk 


LOAD 


load a BASIC program from disk 


MERGE 


merge an ASCII-format BASIC 




program on disk with one 




currently in RAM 


RUN"p rogram" 


load and execute a BASIC 




program stored on disk 


SAVE 


save the resident BASIC program 




on disk 
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Statement and functions discussed under "File Access' 



OPEN 


Open a file for access (create the 




file if necessary) 


CLOSE 


Close access to the file 


INPUT # 


Read from disk, sequential mode 


LINE INPUT* 


Read a line of data, sequential 




mode 


PRINT* 


Write to disk, sequential mode 


GET 


Read from disk, random access 




mode 


PUT 


Write to disk, random access 




mode 


FIELD 


Assign field sizes and names to 




random access file buffer 


LSET 


Place value in specified buffer 




field, add blanks on the right 




to fill field 


RSET 


Place value in specified buffer 




field, add blanks on the left 




to fill field 



Functions 
CVD 

CVI 
CVS 

EOF 
LOF 
MKD$ 

MKI$ 
MKS$ 



Restore double-precision number 

to numeric form after GETting 

from disk 
Restore integer to numeric form 

after GETting from disk 
Restore single-precision number 

to numeric form after 

GETting from disk 
Check to see if end of file 

encountered during read 
Return number of last record in 

file 
Convert double-precision number 

to string so it can be PUT 

on disk 
Convert integer to string so it can 

be PUT on disk 
Convert single-precision number 

to string so it can be PUT 

on disk 
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File Manipulation 

KILL (delete a file from the disk) 



KILL exp$ 

where epx$ defines a file specification for an existing file 



This command works like the TRSDOS KILL command - see 
TRSDOS Library Commands. 

Example: 
KILU'OLDFILE/BflS. PSW1 

deletes the file specified from the first drive which contains it. 

Do not KILL an open file, or you may destroy the contents of the 
diskette. (First CLOSE the open file.) 

LOAD (load BASIC program file from disk) 



LOADexp$ [,R] 

where exp$ defines a filespec for a BASIC program file stored 
on disk 

R tells BASIC to RUN the program after it is 
loaded 



This command loads a BASIC program file into RAM; if the R 
option is used, BASIC will proceed to RUN the program 
automatically; otherwise, BASIC will return to the command 
mode. 

LOAD without the R option wipes out any resident BASIC program, 
clears all variables, and closes all open files. LOAD with the R 
option deletes the resident program and clears all variables, but does 
not close the open files. 

LOAD with the R option is equivalent to the command RUN exp$,R. 
Either of these commands can be used inside programs to allow 
program chaining — one program calling another, etc. 

If you attempt to LOAD a non-B ASIC file, a DIRECT STATEMENT 
IN FILE or LOAD FORMAT ERROR will occur. 
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Examples: 
L0AD"PR0G1/BAS:2" 



Clears resident BASIC program and 
loads PROG1/BAS from drive 2; 
returns to BASIC command mode. 



1 REM . . . INSTRUCTIONS Example of chaining two programs 

— the first may be used to give 
instructions and then to load the 
"working" part of the program 

1000 LOAD"PROG2/BAS",R (PROG2/BAS). Note that line 

1000 is equivalent to: 
1000 RUN"PROG2/BAS" 

MERGE 

(merge disk program with resident program) 



MERGE exp$ 



where exp$ defines a filespec for an ASCII-format BASIC 
disk file, e.g., a program saved with the 
A-option. 



MERGE is similar to LOAD — except that the resident program is 
not wiped out before the new program exp$ is loaded. Instead, 
exp$ is merged into the resident program. 

That is, program lines in exp$ will simply be inserted into the 
resident program in sequential order. If line numbers in exp$ 
coincide with line numbers in the resident program, the resident lines 
will be replaced by those from exp$. 



PROGRAM IN DISK PROGRAM IN RAM MERGED PROGRAM IN RAM 



PROGRAM LINE NUMBERS 




10 



20 



30 



40 



50 



60 



70 



90 



m 



20 



30 



40 



50 



60 



70 



mn 



too 



1*0 



120 
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MERGE provides a convenient means of putting modular programs 
together. For example, an often-used set of BASIC subroutines can 
be tacked onto a variety of programs with this command. 

For example, suppose the following program is in RAM: 

16 REM. . . MAIN PROGRAM 

26 GOSUB 1000 

30 REM. . . MORE PROGRRM LINES HERE 

399 END 

1000 REM. . . NEED TO RDD SUBROUTINES HERE 

1010 REM. . . SO USE MERGE COMMAND 

1020 PRINT"SUBROUTINE NOT AVAILABLE" : RETURN 

And suppose the following program is stored on disk in ASCII format: 

1000 REM. . . BEGINNING OF SUBROUTINE 

1010 PRINT"EXECUTING SUBROUTINE. . . " 

1020 REM. . . MORE PROGRAM LINES HERE 

1100 RETURN 

Assuming the subroutine program is named SUB /TXT, then we 
could MERGE it with the statement: 

MERGE"SUB/fXT" 
and the resultant program in RAM would be: 

10 REM. . . MAIN PROGRAM 

20 GOSUB 1000 

30 REM. . . MORE PROGRAM LINES HERE 

999 END 

1000 REM. . . BEGINNING OF SUBROUTINE 
1010 PRINT-'EXECUTING SUBROUTINE. . . " 
1020 REM. . . MORE PROGRAM LINES HERE 
1100 RETURN 

Note that MERGE closes all files and clears all variables. Upon 
completion, BASIC returns to the command mode. 
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RUN"program" 

(load and execute a program from disk) 



RUNexpS [,R] 

where exp$ defines the filespec for a BASIC program 
stored on disk. R leaves open files open 



If the R-option is not selected, all open files will be closed. 

When the command is executed, any resident BASIC program will 
be replaced by the program contained in exp$. 

Example: 

RUN"D1SKDUMP/BRS U EHI3 
Loads and executes the BASIC sector-dump program. 
Suppose you save the following program on disk with the name 
"PROG1/BAS": 

16 PRINT"PR0G1 EXECUTING. . . " 
20 RUN !! PRGG2/BfiS" 

And save this program on disk with the name "PROG2/BAS" : 

10 PRINT"PRGG2 EXECUTING. . . " 
20 RUH"PRGGl/6fiS" 

Now type: mmmmmmm 

RUN"PR0G1/BRS QZEQ3 

and you'll see a simple example of program chaining. 

Hold down the BREAK key to interrupt the program chain. 

SAVE (save program onto disk) 



SAVEexp$ [,A1 

where exp$ defines the file-name and optional 

extension, password, and drive to be used. 
If the file-name already exists, its previous 
contents will be lost as the file is re-created. 

A causes the file to be stored in ASCII rather 
than compressed-format. 



This command lets you save your BASIC programs on disk. You can 
save the program in compressed or ASCII format. 
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Using compressed-format takes up less disk space and is faster during 
both SAVEs and LOADs. This is the way BASIC programs are 
stored in RAM. 

Using the ASCII option makes it possible to do certain things that 
cannot be done with compressed-format BASIC files. 

Examples: 

• The MERGE command requires that the disk file be in 
ASCII form. 

You can use the TRSDOS commands LIST and PRINT with 
ASCII-format files. 

• Programs which read in other programs as data will typically 
require that the data programs be stored in ASCII. 

Useful conventions for placing extensions on BASIC programs: 
For compressed-format programs, use the extension /BAS. 
For ASCII format programs, use the extension /TXT. 

Examples of SAVE command: 

SflVE"FILEl/BflS. J0HN0.D0E:3" 

saves the resident BASIC program in compressed-format with the 
file name FILE1, extension /BAS, password JOHNQDOE; the 
file is placed on drive :3. 

SRVE"MflTHPflKyTXT M , Fi 

saves the resident program in ASCII form, using the name 
MATHPAK/TXT, on the first non write-protected drive. 

Upon completion of a SAVE, BASIC returns in the command mode. 
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File Access 

This section is divided into four parts: 

1) Creating files and assigning buffers — OPEN and CLOSE 

2) Statements and functions 

3) Sequential I/O techniques 

4) Random I/O techniques. 

If this is your first experience with disk file access, you should 
concentrate on parts 1 , 3 and 4, perhaps just skimming through 
part 2 to get a general idea of how the functions and statements 
work. Later you can go back to part 2 and learn the details of 

Creating files and assigning buffers 

During the initialization dialog, you type in a number in response to 
HOW MANY FILES? The number you type in tells BASIC how 
many buffers to create to handle your disk accesses (reads and 
writes). 

Each buffer is given a number from 1 to 15. If you type: 

HOW MRNV FILES? 4 QUEED 
then BASIC sets aside four buffers, numbered 1,2,3 and 4. 

You can think of a buffer as a waiting area that data must pass 
through on the way to and from the disk file. When you want to 
access a particular file, you must tell BASIC which buffer to use 
in accessing that file. You must also tell BASIC what kind of 
access you want — sequential output, sequential input, or random 
input/output. 

All this is done with the OPEN statement, and "undone" with the 
CLOSE statement. 
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OPEN 

(Assign a buffer to a file and set mode) 



OPEN expl$,nmexp,exp2$ 



where expl$ 



is a string expression or constant of which 
only the first character is significant; this 
character specifies the mode in which the 
file is to be opened: 

expl$- access mode 



I 

O 

R 



sequential input 
sequential output 
random I/O 



nmexp has a value from 1 to 15, and tells BASIC 
which buffer to assign to the file specified 
by exp2$ 

exp2$ defines a TRSDOS file specification 



This statement makes it possible to access a file. expl$ determines 
what kind of access you'll have via the specified buffer; nmexp 
determines which buffer will be assigned to the file; and exp2$ names 
the file to be accessed. If exp2$ does not exist, then TRSDOS may 
or may not create it, depending on the access mode. 

Note: nmexp (buffer number) cannot exceed the number you 

entered for the FILES? question during initialization. If you 
entered: 

HOW MANY FILES? Z 

then nmexp can have the value 1 or 2. 

Examples of OPEN statements: 

160 OPEN "OM, "CLIENTLS/TXT" 

Opens the file "CLIENTLS/TXT" for sequential output. Buffer 1 
will be used. If the file does not exist, it will be created. If it already 
exists, then its previous contents are lost. (This is explained under 
"Sequential I/O Techniques".) 

100 OPEN "1M "PROGl/TXT:!" 

Opens the file "PROG 1 /TXT" on drive 1 for sequential input. Buffer 
| is assigned to the file. If PROG 1 /TXT does not exist on drive 1, an 
error message is returned — since you can't input from a non-existent 
file! 
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198 INPUTMODE <L 0, R) H ; MODE* 

110 INPUT"BUFFER NUMBER"; BUFFERS 

129 INPUT'TILE SPECIFICATION"; FILESPEC* 

136 OPEN MODE*, BUFFER'/., FILESPEC* 

This sequence of statements lets you provide the arguments for the 
OPEN statement during program execution. The first character of 
MODES sets the access mode, BUFFER% determines which buffer 
will be used, and FILESPEC $ gives the file specification. 

QPEN ,, R M , 2, "DATA/BAS. SPECIAL" 

Opens the file DATA/BAS with password SPECIAL, in the random 
I/O mode, using buffer number 2. If DATA/BAS does not exist, 
it will be created on the first non write-protected drive. 

While a file is open, it is referenced by the buffer-number which was 
assigned to it. Examples: 

GET buffer-number 
PUT buffer-number 
PRINT ^buffer-number 
INPUT # b uffer-n umber 

All these statements will reference the file which was OPENed via 
buffer-number . The mode must be correct. 

Once a buffer has been assigned to a file with the OPEN statement, 
that buffer cannot be used in another OPEN statement. You have 
to CLOSE it first. 



More on Buffer Assignments 

Two or more buffers may be assigned to the same file for sequential 
input (I-mode). However, only one buffer at a time may be assigned 
to a file for sequential output (O-mode) or random access R-mode. 



For example: 

10 OPEN " I M, ■TEST/TXT :i" 
20 OPEN " I ", 2, "TEST/TXT : 1" 

Now TEST/TXT can be accessed via buffers 1 and 2 for sequential 
input. 
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CLOSE (dose access to the file) 



CLOSE [nmexp [,nmexp . . .] ] 

where nmexp has a value from 1 to 15, and refers to the 
file's buffer-number (assigned when the 
file was opened). If nmexp is omitted, all 
open files will be closed. 



This command terminates access to a file through the specified 
buffer(s). If nmexp has not been assigned in a previous OPEN 
statement, then 

CLOSE nmexp 

has no effect. 

Examples of CLOSE statements: 

CLOSE 1/2.8 

Terminates the file assignments to buffers 1, 2 and 8. These buffers 
can now be assigned to other files with OPEN statements. 

CLOSE FIRSTJS+COUNTX 

Terminates the file assignment to the buffer specified by the sum 
(FIRST% + COUNT%). 

Do not remove a diskette which contains an open file - first close 
the file. This is because the last 256 bytes of data may not have 
been written to disk yet. Closing the file will write the data, if it 
hasn't already been written. 

The following actions and conditions cause all files to be 
automatically closed: 



NEW 

RUN HJHds l 

MERGE filespec HJHd;l 
EDITing a file 

Adding or deleting program lines 
Execution of the CLEAR n statement 
Disk Errors 
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INPUT# (sequential read from disk) 



INPUT* nmexp, var[,var . . .] 

where nmexp specifies a sequential input file 
buffer, nmexp-1,2, ... ,1 5 

var is the variable name to contain 
the data from the file 



This statement inputs data from a disk file. The data is input 
sequentially. That is, when the file is first opened, a pointer is set 
to the beginning of the file. Each time data is input, the pointer 
advances. To start over reading from the beginning of the file, you 
must close the file-buffer and re-open it. 

INPUT* doesn't care how the data was placed on the disk - whether 
a single PRINT* statement put it there, or whether it required 10 
different PRINT* statements. What matters to INPUT* are the 
positions of the terminating characters and the EOF marker. 

To INPUT* data successfully from disk, you need to know ahead of 
time what the format of the data is. Here is a description of how 
INPUT* interprets the various characters it encounters when reading 
data. 

When inputting data into a variable, BASIC ignores leading blanks; 
when the first non-blank character is encountered, BASIC assumes it 
has encountered the beginning of the data item. 

The data item ends when a terminating character is encountered or 
when a terminating condition occurs. The particular terminating 
characters vary, depending on whether BASIC is inputting to a 
numeric or string variable. 
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Mere's an important exception to keep in mind in 

When <EN> (a carriage return) is preceded by < LT > 
(a line feed), the < bN> is not taken as a terminator. 
Instead, it becomes a part i){' the data item (string 
variable) or is simply ignored (numeric variable). 

(To enter the <LF> character from the keyboard, 
press the down arrow. To enter the < L:N> character, 

press nana.) 

This exception applies to all cases noted below where 
< EN> is said to be a terminator. 



Numeric Input 

Suppose the data image on disk is 

#1. 234^-33^27$ <EN> 

<EN> denotes a carriage-return character (ASCII code decimal 13). 

Then the statement 

INPUTS!, fi,B,C 

or the sequence of statements 

INPUTS!, fi: INPUTS!, B: INPUTS!, C 

will assign the values as follows: 

A= 1.2345 
B=-33 

C=27 

This works because blanks and < EN > serve as terminators for 
input to numeric variables. The blank before 1.2345 is a "leading 
blank", therefore it is ignored. The blank after 1.2345 is a 
terminator; therefore BASIC starts inputting the second variable at 
the — character, inputs the number —33, and takes the next two 
blanks as terminators. The third input begins at the 2 and ends 
with the 7. 



7-38 



DISK BASIC 



String Input 

When reading data into a string variable, INPUT ignores all leading 
blanks; the first non-blank character is taken as the beginning of the 
data item. 

If this first character is a double-quote ("), then INPUT will evaluate 
the data as a quoted string: it will read in all subsequent characters 
up to the next double-quote. Commas, blanks, and < EN > 
-characters will be included in the string. The quotes themselves 
do not become a part of the string. 

If the first character of the string item is not a double-quote, then 
INPUT will evaluate the data as an unquoted string: It will read in 
all subsequent characters up to the first comma, or < EN > . 
If double quotes are encountered, they will be included in the string. 

For example, if the data on disk is: 

PECOS,#TEXAS "GOOD MELONS" 
Then the statement 

INPUT#1, ft$,B$,C$ 

would assign values as follows: 

A$=PECOS 

B$=pTEXAS "GOOD^MELONS" 

C$= null string 

If a comma is inserted in the data image before the first double quote, 
C$ will get the value, GOOD MELONS. 

These are very simple examples just to give you an idea of how 
INPUT works. However, there are many other ways to input data - 
different terminators, different target variable types, etc. 

Rather than taking a shotgun approach and trying to cover them all, 
we'll give a generalized description of how input works and what 
the terminating characters and conditions are, and then provide 
several examples. 

When BASIC encounters a terminating character, it scans ahead to 
see how many more terminating characters it can include with the 
first terminator. This ensures that BASIC will begin looking for the 
next data item at the correct place. 

The list below defines the various terminating sets INPUT# will 
look for. It will always try to take-in the largest set possible. 
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Numeric-input terminator sets 

end of file encountered 

255th data character encountered 

, (comma) 

<EN> 

<EN> <LF> 

m :..][ <en> ] 

m •••][ <ENXLF>] 



Quoted-string terminator sets 

end of file encountered 

255th data character encountered 

" (double quote) 

" [#...][,] 

"[#...][ <EN> ] 

" [#...][ <EN> <LF>] 



Unquoted-string terminator sets 

end of file encountered 

255th data character encountered 

<EN> [<LF>] 



Here's a flow chart describing how INPUT# assigns data to a variable: 



EXAMINE NEXT 
CHARACTER 



~K~ 




*r 



■> 



PUT IT INTO 
TEMPORARY 
SAVE AREA 



EXAMINE NEXT 
CHARACTER 




e 



PICKUP THE 

TERMINATOR 

SET 



GET DATA FROM 
TEMPORARY 
SAVE AREA 



-> 



EVALUATE IT 



-> 



ASSIGN TO 
VARIABLE 



■^ 
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The following table shows how various data images will be read-in by 
the statement: 



INPUT#1, Fb B* C 
Ex.# Image on disk 



3 1 ,,2,3,4 <EN> 



4 l,3,end-of-file 



Values assigned 



1 #123.45$ <ENXLF>R2E4^7000<EN> A-123.45 

B=82000 
C=7000 

2 0^3<LF><EN> 4 <EN>5 <EN> A12eof A=34 

B=5 
C=0 



A=l 
B=0 
C=2 

A=l 
B=2 

C=0 end of file error 



In Example 2 above, why does variable C get the value 0? When the 
input reaches the end of file, it terminates the last data item, which 
then contains "A12". This is evaluated by a routine just like the 
BASIC VAL function -which returns a zero since the first character 
of "A12" is non-numeric. 

In Example 3, when INPUT* goes looking for the second data item, 
it immediately encounters a terminator (the comma); therefore 
variable B is given the value zero. 

The following table shows how various data images on disk will be 
read by the statement: 

INPUT#l,fi$,B$ 



Ex.# Image on disk 
1 MV>"ROBERTS,J."ROBERTS,M.N eof 



Values assigned 

A$=ROBERTS,J. 
B$=ROBERTS,M.N. 



2 0WROBERTS,J.,WROBERTS,M.N. <EN> A$=ROBERTS 

B$=J. 



3 THE WORD "QUO",12345.789 <EN> 



A$=THE WORD "QUO' 

B$=12345.789 



4 BYTE<LF> < EN > UNIT OF MEMORY eof A$=BYTE< LF >< EN > UNIT OF MEMORY 

B$=null (eof error) 
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In example 3, the first data item is an unquoted string, therefore the 
double-quotes are not terminators, and become part of A$. 

In example 4, the <EN > is preceded by an < LF >, therefore it 
does not terminate the first string; both <LF> and < EN > 

are included in A$. 



Technical Note: The above discussion ignores the role of the input 
buffer in the sequential input process. Actually, DISK BASIC 
always reads in 256-byte data records into the buffer, and then sorts 
through what's in the buffer to "satisfy" the INPUT* variable list. 
That's why 

160 INPUT8JL FTC 
200 INPUT*!, BY. 

do not necessarily require two disk accesses. The 256-byte record 
in the buffer can contain enough data for A%, B% and more. 



LINE INPUT# 

(read a line of text from disk) 



LINE INPUT #nmexp,var$ 

where nmexp specifies a sequential output file buffer, 
nmexp=l,2, ... ,15 

var$ is the variable name to contain the string 
data 



Similar to LINE INPUT from keyboard, this statement reads a 
"line" of string data into var$. This is useful when you want to 
read an ASCII-format BASIC program file as data, or when you want 
to read in data without following the usual restrictions regarding 
leading characters and terminators. 

LINE INPUT (or LINEINPUT - the space is optional) reads 
everything from the first character up to: 

1 ) an < EN > character which is not preceded by < LF > 

2) the end-of-file 

3) the 255th data character (this 255 character is included 
in the string) 

Other characters encountered - quotes, commas, leading blanks, 
< LF > < EN > pairs - are included in the string. 
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For example, if the data looks like: 



10 CLEAR 500 <EN> 

20 OPEN "I",l, "PROG" <EN> 



then the statement 

LINEINPUT#l,fl* 

could be used repetitively to read each program line, one line at a 
time. 



PRINT# (sequential write to disk file) 



?RlNT#nmexp, [ USING formats ;] exp[p exp . . .] 

where nmexp specifies a sequential output file buffer, 
nmexp=\,2, ... ,15 

formats is a sequence of field specifiers used with 
the USING option 

p is a delimiter placed between every two 
expressions to be PRINT ed to disk; either 
a semi-colon or comma can be used 
(semi-colon is preferable) 

exp is the expression to be evaluated and 
written to disk 



This statement writes data sequentially to the specified file. When 
you first open a file for sequential output, a pointer is set to the 
beginning of the file, therefore your first PRINT* places data at 
the beginning of the file. At the end of each PRINT* operation, the 
pointer advances, so the values are written in sequence. 

A PRINT* statement creates a disk image similar to what a PRINT 
to display creates on the screen. Remember this, and you'll be able 
to set up your PRINT* list correctly for access by one or more 
INPUT statements. 

PRINT* does not compress the data before writing it to disk; it 
writes an ASCII-coded image of the data. 
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For example, if A= 123.45 

PRINT*!, fi 
will write a nine-byte character sequence onto disk: 

#123.45tf <EN> 

The punctuation in the PRINT list is very important. Unquoted 
commas and semi-colons have the same effect as they do in regular 
PRINT to display statements. 

For example, if A=2300 and B= 1.303, then 

PRINT#l,fbB 
places the data on disk as 

tf 2300 WW WW 1 -303 tf < EN > 

The comma between A and B in the PRINT* list causes 10 extra 
spaces in the disk file. Generally you wouldn't want to use up 
disk space this way, so you should use semi-colons instead of 
commas. 

PRINT#1,A;B 

writes the data as: 

2300 1.303 <EN> 

PRINT* with numeric data is quite straightforward — just remember 
to separate the items with semi-colons. 

PRINT* with string data requires more care, primarily because you 
have to insert delimiters so the data can be read back correctly. In 
particular, you must separate string items with explicit delimiters 
if you want to INPUT* them as distinct strings. 

For example, suppose: 

A$="JOHN Q. DOE" and B$=" 100-0 1-001" 

Then: 

PRINTttL fi*;B* 

would produce this image on disk: 
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JOHN Q. DOElOO-01-001 <EN> 
which could not be INPUT back into two variables. 
The statement: 

PRINTttl, fi*.;",";B* 
would produce: 

JOHN Q. DOE, 100-01-001 
which could be INPUT* back into two variables. 

This method is adequate if the string data contains no delimiters — 
commas or < EN > —characters. But if the data does contain 
delimiters or leading blanks that you don't want to ignore, then you 
must supply explicit quotes to be written along with the data. 
For example, suppose A$="DOE, JOHN Q." B$="100-01-001" 

If you use 

PRINTttL flfo'V'iB* 

the disk image will be: 

DOE, JOHN Q., 100-0 1-001 <EN> 
When you try to input this with a statement like 

INPUT#2, fl$, B$ 

A$ will get the value "DOE", and B$ will get "JOHN Q." - because 
of the comma after DOE in the disk image. 

To write this data so that it can be input correctly, you must use 
the CHR$ function to insert explicit double quotes into the disk 
image. Since 34 is the decimal ASCII code for double quotes, use 
CHR$(34) as follows: 

PRINTS CHR$<34>; fi$; CHR$C4); B$ 

this produces the disk image 

"DOE, JOHN Q."100-01-001 <EN> 
which can be read with a simple 

INPUT#2, fi$, B$ 
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Note: You can also use the CHR$ function to insert other delimiters 
and control codes into the file, for example: 

CHR$( 10) < LF > Line Feed 

CHR$(13) carriage return (<EN>character) 

CHR$( 1 1 ) or CHR$( 1 2) line-printer top-of-form 

USING Option 

This option makes it easy to write files in a carefully controlled 
format. You could create a report file this way, which then could be 
LISTed or PRINTed (TRSDOS commands). 

Or you could use this option to control how many characters of a 
value are written to disk. 

For example, suppose: 

A$="LUDWIG" 

B$="VAN" 

C$="BEETHOVEN" 

Then the statement 

PRINTttL USING" ! . ! . "/. Y.*i Mi B$; C* 
would write the data in nickname form: 

L.V.BEET <EN> 

(In this case, we didn't want to add any explicit delimiters.) See the 
PRINT USING description in the LEVEL II BASIC Reference 
Manual for a complete explanation of the field-specifiers. 

Technical Note: The above discussion ignores the role of the 
output buffer in the sequential write process. Actually, the data is 
first placed into the buffer, and then, as 256-byte records are filled, 
the data is written to the disk file. That's why there isn't always a 
disk access during execution of each PRINT* statement. 
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Random Access Statements 

FIELD 

(organize a random file-buffer into fields) 



FIELD nmexp,nmexpl AS varl$ [,nmexp2 AS var2$ . . .] 


where nmexp 


specifies a random access file buffer, 




nmexp=\,2, ... ,15 


nmexpl 


specifies the length of the first field, 


varl$ 


defines a variable name for the first field 


nmexp2 


specifies the length of the second field 


var2$ 


defines a variable name for the second field 




subsequent nmexp AS var$ pairs define 




other fields in the buffer 



Before FIELDing a buffer, you must use an OPEN statement to 
assign that buffer to a particular disk file (must use random access 
mode). Then use the FIELD statement to organize a random file 
buffer so that you can pass data from BASIC to disk storage and 
vice-versa. 

Each random file buffer has 255 bytes which can store data for 
transfer from disk storage to BASIC or from BASIC to disk. 
However, you need a way to access this buffer from BASIC so 
that you can either read the data it contains or place new data 
in it. The FIELD statement provides the means of access. 

You may use the FIELD statement any number of times to 
"re-organize" a file buffer. FIELDing a buffer does not clear 
the contents of the buffer; only the means of accessing the buffer 
(the field names) are changed. Furthermore, two or more field 
names can reference the same area of the buffer. 



Examples: 



FIELD 1, 255 AS R$ 



This statement tells BASIC to assign the entire 255-byte buffer to 
the string variable A$. If you now print A$, you will see the contents 
of the buffer. Of course, this value would be meaningless unless you 
have used GET to read a 255-byte record from disk. 

Note: All data — both strings and numbers — must be placed into 
the buffer in string form. There are three pairs of functions 
(MKI$/CVI,MKS$/CVS,MKD$/CVD) for converting numbers to 
strings and vice-versa. See "Functions", below. 
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FIELD 3, 16 RS NM*, 25 AS RD$, 18 AS CY*, 2 AS ST*, 7 FiS ZP* 

The first 16 bytes of buffer 3 are assigned the buffer name NM$; the 
next 25, ADS; the next 10, CY$; the next 2, ST$; and the next 
7, ZP$. The remaining 195 bytes of the buffer are not fielded at all. 



More on field names 

Field names, like NM$,AD$,CY$,ST$ and ZP$, are not string 
variables in the ordinary sense. They do not consume the string 
space available to BASIC. 

Instead, they point to the buffer field which you assigned with the 
FIELD statement. That's why you can use: 

106 FIELD 1,255 AS fl* 

without worrying about whether 255 bytes of string space are 
available for A$. 

If you use a buffer field name on the left side of an ordinary assignment 
statement, that name will no longer point to the buffer field ; therefore 
you won't be able to access that field using the previous field name. 

For example, 

fi*=B* 
nullifies the effect of the FIELD statement above (line 100). 

During random input, the GET statement places data into the 
255-byte buffer, where it can be accessed using the field names 
assigned to that buffer. During random output, LSET and RSET 
place data into the buffer, so you can then PUT the buffer contents 
into a disk file. 

Often you'll want to use a dummy variable in a FIELD statement 
to "pass over" a portion of the buffer and start fielding it somewhere 
in the middle. For example: 

FIELD 1,15 AS CLIENT*<1>, 112 AS HIST*<1) 

FIELD 1,128 RS DUMMY*, 15 AS CLIENT*02), 112 RS HIST*«.2> 

In the second FIELD statement, DUMMY $ serves to move the starting 
position of CLIENT$(2) to position 129. In this manner, two 
identical "subrecords" are defined on buffer number 1 . We won't 
actually use DUMMY $ to place data into the buffer or retrieve it from 
the buffer. 
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The buffer now "looks" like this: 



15 


112 


1 


15 


112 


CL$ HIST$ X 
(I) (1) 

■< DUMMY$ ► 


CL$ 
(2) 


HIST$ 
(2) 



Note that only one byte (the 128th byte) is left unused in this field 
structure. 



VjrlLl 

(read a record from disk — random access) 



GET nmexpl[,nmexp 2] 

where nmmexpl specifies a random access file buffer, 
nmexpl=\,2, . . . ,15 
nmexp2 specifies which record to GET in the 

file; if omitted, the current record will 
be read. 



This statement gets a data record from a disk file and places it in the 
specified buffer. Before GETting data from a file, you must open 
the file and assign a buffer to it. That is, a statement like: 

OPEN "R",nmexpl,filespec 
is required before the statement: 

GET nmexpl,nmexp2 

When BASIC encounters the GET statement, it looks at the buffer's 
control block, and obtains: 

• the information needed to access the file 

• the mode in which this buffer was set up (must be R) 

• the current record number 

• The EOF (end-of-file) record number, i.e., the highest 
numbered record in the file 

• lots of other information for internal use 

BASIC then reads record nmexp2 from the file and places it into the 
buffer. If you omit the record number, it will read the current record. 

The "current record" is the record whose number is one higher than 
that of the last record accessed. The first time you access a file via 
a particular buffer, the current record is set equal to 1 . 
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For example: 

Program statement Effect 



1 000 OPEN"R", 1 , "NAME/B AS" Open NAME/B AS for random 

access using buffer 1 

1010 FIELD 1 , . . . Structure buffer 

1020 GET 1 GET record 1 into buffer 1 
1025 REM . . . ACCESS BUFFER 

1030 GET 1 ,3 GET record 3 into buffer 1 
1035 REM . . . ACCESS BUFFER 

1 040 GET 1 ,25 GET record 25 into buffer 1 
1046 REM . . . ACCESS BUFFER 

1050 GET 1 GET record 26 into buffer 1 

If you attempt to GET a record whose number is higher than that 
of the end-of-file record, BASIC will fill the buffer with hex zeroes, 
and no error will occur. 

To prevent this from occurring, you can use the LOF function to 
determine the number of the highest numbered record. 



PUT 

(write a record to disk - random access) 



PUT nmexpl[,nmexp2] 

where nmexpl specifies a random access file buffer, 
nmexp-\ ,2, ... ,15 

nmexp2 specifies the record number in the file, 
nmexp2=l,2, . . , up to 335, depending 
on how much space is available on the 
disk; if nmexpl is omitted, the current 
record number is assumed. 



This statement moves data from a file's buffer into a specified place 
in the file. Before PUTing data in a file, you must: 

1 ) OPEN the file, thereby assigning a buffer and defining the 
access mode (must be R); 

2) FIELD the buffer, so you can 

3) place data into the buffer with LSET and RSET statements. 
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When BASIC encounters the statement: 

PUT nmexp,nmexp2 
it does the following: 

• Gets the information needed to access the disk file 

• Checks the access mode for this buffer (must be R) 

• Acquires more disk space for the file if necessary to 
accommodate the record indicated by nmexp2 

• Copies the buffer contents into the specified record of the 
disk file 

• Updates the current record number to equal nmexp2+l 

The "current record" is the record whose number is one higher than 
the last record accessed. The first time you access a file via a 
particular buffer, the current record is set equal to 1 . 

If the record number you PUT is higher than the end-of-file record 
number, then nmexp2 becomes the new end-of-file record number. 

This has an important implication. When you PUT a record whose 
number exceeds the EOF record number, space is allocated on the 
disk to accommodate the new highest record number plus all 
lower-numbered records. For example, 

PUT nmexp,336 

will always produce a DISK FULL message, since TRSDOS attempts 
to find space for all records from 1 to 336 - and 335 is the maximum 
number of records available on a diskette. 
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Examples (assume a file named SAMPLE/BAS exists and that you 
have previously written 10 records to it, so that LOF=10): 



Program statement 

1000 OPEN"R",l, "SAMPLE/BAS" 

1010 FIELD 1, 

1020 LSET 

1030 PUT 1 

1035 LSET 

1040 PUT 1,30 



Effect 



1045 
1050 

1055 
1060 



LSET 

PUT 1,25 



LSET 
PUT 1 



Open SAMPLE/BAS for random 

address under buffer 1 
Prepare buffer 
Place data in buffer 
Copy buffer contents into 

current record (=#1) 
Place data in buffer 
Acquire disk space for records 

2 through 30 and copy 

buffer contents into record 

30;setLOF=30 
Place data in buffer 
Copy buffer contents into 

record 25 
Place data in buffer 
Copy buffer contents into 

current record (=#26) 
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LSET and RSET 

(place data in a random buffer field) 



LSET var$ = exp$ and RSET var$ = exp$ 
where var$ is a field name 

exp$ contains the data to be placed in the buffer 
field named by var$ 



These two statements let you place character-string data into fields 
previously set up by a FIELD statement. 

For example, suppose NM$ and ADS have been defined as field 
names for a random file buffer. NM$ has a length of 18 characters, 
and ADS has a length of 25 characters. 

Now we want to place the following information into the buffer 
fields so it can be written to disk: 

name: JIM CRICKET, JR. 

address: 2000 EAST PECAN ST. 

This is accomplished with the two statements: 

LSET NM*= M JIM CRICKET, JR. " 
LSET flD$="2000 EAST PECRN ST. " 

This puts the data in the buffer as follows: 



JIMtfCRICKET,JR.#tf 



2000#EAST#PEC AN# ST.###tf 



NM$ AD$ 

Note that filler spaces were placed to the right of the data strings 
in both cases. If we had used RSET instead of LSET statements, the 
filler spaces would have been placed on the left. This is the only 
difference between LSET and RSET. 

For example: 

RSET NM*=" JIM CRICKET, JR. " 
RSET AD*="2000 ERST PECAN ST. H 

places data in the fields as follows: 



W0JIMflCRICKET,JR. 

NM$ 



0lOTW2OOOflEAST#PECANflST. 
AD$ 
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If a string item is too large to fit in the specified buffer field, it is 
always truncated on the right. That is, the extra characters on the 
right are ignored. 



CVD, CVI and CVS 

(restore string to numeric form) 



CVD(exp$) 



where exp$ defines an eight character string; exp$ is 
typically the name of a buffer-field 
containing a numeric string. If LEN(exp$)< 8, 
an ILLEGAL FUNCTION CALL error occurs; 
if LEN(exp$)>8, only the first eight characters 
are used. 



CVl(exp$) 



where exp$ defines a two-character string; exp$ is 
typically the name of a buffer-field 
containing a numeric string. If LEN(exp$)<2, 
an ILLEGAL FUNCTION CALL error occurs; 
if LEN(exp$)>2, only the first two characters 
are used. 



CVS(exp$) 



where exp$ defines a four-character string; exp$ is 
typically the name of a buffer-field 
containing a numeric string. If 
LEN(exp5)<4, an ILLEGAL FUNCTION 
CALL error occurs; if LEN(expS)>4, 
only the first four characters are used. 



These functions let you restore data to numeric form after it is read 
from disk. Typically the data has been read by a GET statement, and 
is stored in a random access file buffer. 

The functions CVD, CVI, CVS are inverses of MKD$, MKI$, and 
MKS$, respectively. 

For example, suppose the name GROSSPAY$ references an eight- 
byte field in a random-access file buffer, and after GETting a record, 
GROSSPAY$ contains a MKD$ representation of the number 
13123.38. 
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Then the statement: 

PRINT CVD<GR0S5PflY$>-TRXES 

prints the result of the difference, 13123.38-TAXES. Whereas the 
statement: 

PRINT GROSSPRY$-TflXES 

will produce a TYPE MISMATCH error, since string values cannot be 
used in arithmetic expressions. 

Using the same example, the statement 

fl#=CVD<QROSSPflV*) 

assigns the numeric value 13 123.38 to the double-precision variable 

A#. 

EOF (end-of-file detector) 



EOF(nmexp) 



where nmexp specifies a file buffer, 
nmexp=\,2, ... ,15 



This function checks to see whether all characters up to the end-of- 
file marker have been accessed, so you can avoid INPUT PAST END 
errors during sequential input. 

Assuming nmexp specifies an open file, then EOF(nmexp) returns 
(false) when the EOF record has not yet been read, and -1 (true) 
when it has been read. 



Examples: 



IF EGR5) THEN PR I NT "END OF FILE"FILENM$ 
IF EQFCNir/.) THEN CLOSE NIT/. 
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The following sequence of lines reads numeric data from DATA/TXT 
into the array A( ). When the last data character in the file is read, 
the EOF test in line 30 "passes", so the program branches out of the 
disk access loop, preventing an INPUT PAST END error from 
occurring. Also note that the variable I contains the number of 
elements input into array A( ). 

5 DIM fi<166) 'ASSUMING THIS IS R SAFE VALUE 
16 OPEN "IM, "DflTfl/TXT" 

29 I%=0 

30 IF EQF<1> THEN 70 
40 INPUT#l,fl<IX) 

50 I5S=I5i+l 
60 GOTO 30 
70 REM PROGRAM CONTINUES HERE AFTER DISK INPUT 

LOF (get end-of-file record number) 



LOF (nmexp) 



where nmexp specifies a random access buffer 
nmexp=l,2, ... ,15 



This function tells you the number of the last, i.e., highest numbered, 
record in a file. It is useful for both sequential and random access. 

For example, during random access to a pre-existing file, you often 
need a way to know when you've read the last valid record. LOF 
provides a way. 

Examples: 

10 OPEN "RV1, "UNKNOWN/TXT" 

20 FIELD 1,255 AS A$ 

30 F0RIK=1 TO L0F<1) 

40 GET 1, IV. 

50 PRINT A* 

60 NEXT 

In line 30, LOF(l) specifies the highest record number to be accessed. 

Note: If you attempt to GET record numbers beyond the end-of-file 
record, BASIC simply fills the buffer with hexadecimal zeroes, and 
no error is generated. 

When you want to add to the end of a file, LOF tells you where to 
start adding: 

100 IK=L0F<1)+1 'HIGHEST EXISTING RECORD 

110 PUT 1, 17. 'ADD NEXT RECORD 
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MKD$, MKI$ and MKS$ 

(convert data, numeric-to-string) 



MKD$(nmexp) 

where nmexp is evaluated as a double-precision number 

MKl$(nmexp) 

where nmexp is evaluated as an integer, 

— 321 68<=nmexp <321 68; if nmexp exceeds 
this range, an ILLEGAL FUNCTION CALL 
error occurs; any fractional component in 
nmexp is truncated 

MKS$(nmexp) 

where nmexp is evaluated as a single-precision number 



These functions change a number to a "string". Actually the byte 
values which make up the number are not changed; only one byte, 
the internal data-type specifier, is changed, so that numeric data can 
be placed in a string variable. (See LEVEL II Reference Manual, 
VARPTR Function, for details of internal number representation.) 

That is: 

MKD$ returns an eight-byte string 
MKI$ returns a two-byte string 
MKS$ returns a four-byte string 

Examples: 

ASC(MKI$(I%)) equals the lsb of 1%, i.e., (1% AND 255) 
ASC(RIGHT$(MKI$(I),l))=themsb of 1%, i.e., INT(I%/256) 

LSET AVG$=MKS$(0.123) 

AVG$ would typically reference a four-byte random buffer field. 
Now it contains a representation of the single-precision number 
0.123. 
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LSET TflLLV*=MKI*<I?i) 

Field name TALLY $ would now contain a two-byte representation 
of the integer 1%. 

fl$=MKI*<8/I> 

A$ becomes a two-byte representation of the integer portion of 8/1. 
Any fractional portion is ignored. Note that A$ in this case is a 
normal string variable, not a buffer-field name. 

Suppose BASEBALL/BAT (a non-standard file extension) has been 
opened for random access using buffer 2, and the buffer has been 
FIELDed as follows: 

field: NM$ YRS$ AVG$ HR$ AB$ ERNING$ 
length: 16 2 4 2 4 4 

NM$ is intended to hold a character string; AVG$, AB$ and 
ERNINGS, converted single-precision values; YR$ and HR$, 
converted integers. 

Suppose we want to write the following data record: 

SLOW LEARNER played 38 years ; lifetime batting average .123; 
career homeruns, 1 1 ; at bats, 32768; . . . , earnings —13.75. 

Then we'd use the make-string functions as follows: 

1060 LSET NM$="5L0W LEARNER" 
1018 LSET YRS$=MKI$<38) 
1020 LSET flVG*=MKS*<. 123) 
1030 LSET HR$=MKI$<11) 
1040 LSET RB*=MKS*< 32768) 
1050 LSET ERNING$=MKS$<-13. 75) 

After this sequence, you can write SLOW LEARNER'S information 
to disk with the PUT statement. When you read it back from disk 
with GET, you will need to restore the numeric data from string 
to numeric form, using CVI and CVS functions. 
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Sequential Access Techniques 

Sequential input/output is the simplest way to store data in disk 
files and retrieve it into BASIC variables. 

To write to disk, you open a file for sequential output, PRINT* the 
data, and close the file. To read the data back, you simply open 
the file for sequential access and INPUT* the data directly into 
BASIC variables — in the same order as the data was written onto 
the disk. 

Sequential Output - An Example 

Suppose we want to store a table of English-to-metric conversion 
constants: 

English unit Metric equivalent 



1 inch 2.54001 centimeters 

1 mile 1.60935 kilometers 

1 acre 4046.86 sq. meters 

1 cubic inch 0.01638716 liter 

1 U.S. gallon 3.785 liters 

1 liquid quart 0.9463 liter 

1 lb (avoir) 0.45359 kilogram 

First we decide what the data image is going to be. Let's say we want 
it to look like this: 

english unit—>metric unit, factor <EN> 
For example, the stored data would start out: 

IN->CM,tf2.54001tf <EN> 
The following program will create such a data file. 

Note: <EN> represents a carriage return, hex OD. 
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10 0PEN"0",1, "METRIC/TXT" 
26 FORIJi=l TO 7 

39 READ UNIT*, FflCTR 

40 PRINTM, UNIT*; ", "; FflCTR 
50 NEXT 

60 CLOSE 

70 DRTfl IN->CM, 2. 54001, MI->KM, 1. 60935, FiCRE->SQ. M, 4046. 86 

80 DRTfl CU. IN-X.TR,!. 638716E-2, GfiL->LTR, 3. 785 

90 DATA LIQ. QT->LTR, 0. 9463, LB->KG, 0. 45359 

Line 10 creates a disk file named METRIC/TXT, and assigns buffer 1 
for sequential output to that file. The extension /TXT is used because 
sequential output always stores the data as ASCII-coded text. 

Note: If METRIC/TXT already exists, line 10 will cause all its data 
to be lost. Here's why: Whenever a file is opened for sequential 
output, the EOF marker is set to the beginning of the file. In effect, 
TRSDOS "forgets" that anything has ever been written beyond 
this point. 

Line 40 prints the current contents of UNITS and FACTR to the file 
buffer. The disk-write won't actually take place until the buffer is 
filled or you close the file, whichever happens first. Since the string 
items do not contain delimiters, it is not necessary to print explicit 
quotes around them. The explicit comma is sufficient. 

Line 60 closes the file. The EOF marker points to the end of the last 
data item, i.e., 0.45359, so that later, during input, DISK BASIC will 
know when it has read all the data. 
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Sequential Input - An Example 

The following program reads the data from METRIC/TXT into two 
"parallel" arrays, then asks you to enter a conversion problem. 

5 CLEAR 568 

10 DIM UNITS$<9>,FACTR<9> 'ALLOWS FOR UP TO 16 DATA PAIRS 

28 OPEN" I M, "METRIC/TXT" 

25 IJi=6 

30 IF E0F<1> THEN 78 

48 INPUT#1, UNIT*< I%>, FfiCTRU JO 

58 I5i=I?i+l 

68 GOTO 30 

78 REM. . . THE CONVERSION FACTORS HAVE BEEN READ IN 

100 CLS: PRINT TAB<5>"*** ENGLISH TO METRIC CONVERSIONS ***" 

110 FOR ITEM"/.=0TOIJ£-1 

120 PR I NT US I NG M < ## ) >i % " > I TEM& UN I T* < I TEM% ) 

130 NEXT 

140 PRINT6704, "WHICH CONVERSION "; 

158 INPUT CHOICER 

155 PRINT6768, "ENTER ENGLISH QUANTITY"; 

160 INPUT V 

170 PRINT"THE METRIC EQUIVALENT IS n V*FACTR<CH0ICE?O 

180 INPUT "PRESS ENTER TO CONTINUE".: X 

190 PRINT@704,CHR*<31>; "CLEAR TO END OF FRAME 

200 GOTO 140 

Line 20 opens the file for sequential input. The read pointer is 
automatically set to the beginning of the file. 

Line 30 checks to see that the end-of-file record hasn't been read. 
If it has, control branches from the disk input loop to the part of the 
program that uses the newly acquired data. 

Line 40 reads a value into the string array UNIT$( ), and a number into 
the single-precision array FACTR( ). Note that this INPUT list 
parallels the PRINT* list that created the data file (see the section 
"Sequential Output: An example"). This parallelism is not required, 
however. We could just as successfully have used: 

48 INPUT*!, UNIT*< I"/.) : INPUTS FflCTR< IX) 
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How to update a file 



Suppose you want to add more entries into the English-Metric 
conversion file. You can't simply re-open the file for sequential 
output and PRINT# the extra data — that would immediately set 
the end-of-file marker to the beginning of the file, effectively 
destroying the file's previous contents. Do this instead: 

1 ) Open the file for sequential input 

2) Input the entire file and store it 
(typically in one or more arrays) 

3) Close the file 

4) , Add your new entries to the data array, or correct 
existing entries 

5) Re-open the file for sequential output 

6) Output the updated data array to the file 

7) Close the file 

If the file is too large to fit in memory, update it this way: 

1) Open the file for sequential input 

2) Open another new data file for sequential output 

3) Input a block of data and update the data as necessary 

4) Output the data to the new file 

5) Repeat steps 3 and 4 until all data has been read, 
updated, and output to the new file; then go to 
step 6 

6) Close both files 

7) Kill the old data file 

8) Rename the new file (TRSDOS RENAME command) 
to the name of the old file. 
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Sequential LINE INPUT - An Example 

Using the line-oriented input, you can write programs that edit other 
BASIC program files : renumber them, change LPRINTs to PRINTs, 
etc. - as long as these "target" programs are stored in ASCII format. 

The following program counts the number of lines in any disk file 
with the extension "/TXT". 

16 CLEAR 300 

20 INPUT "WHAT IS THE NAME OF THE PROGRAM".; PROG* 

30 IF INSTRXPROG*, VTXT">=0 THEN 11© -REQUIRE /TXT EXTENSION 

40 OPEN" IM, PROG* 

50 r/.=e 

60 IF E0F<1)THEN 90 

70 I5J=IJJ+1: LINE INPUT#1, TEMP* 

80 GOT 060 

90 PR I NT "THE PROGRAM IS"I£"LINES LONG. " 

100 CLOSE: GOTO20 

110 PRINT "FILESPEC MUST INCLUDE THE EXTENSION VTXT'" 

120 GOTO20 

For BASIC programs stored in ASCII, each program line ends with 

an < EN > character not preceded by an < LF > line feed. 

So the LINE INPUT in line 70 automatically reads one entire line at 

a time, into the variable TEMPS. Variable 1% actually does the 

counting. 

To try out the program, save DISKDUMP/BAS as a text file: 

LQAD-'DISKDUMP/BAS" Um3ii 
SAVE"DISKDUMP/TXT",A BSEa 

This gives you a second, ASCII-format version of DISKDUMP. 

Now type in the line-counter program and tell it to examine the 
program DISKDUMP/TXT. 
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Disk Storage during Sequential Access 

One thing that makes sequential access so simple is that you can 
generally ignore the details of disk storage. You just write your data 
and read it back. 

Described below are a few of the technical details and hints you 
should keep in the back of your mind. In some situations, they will 
become important. 

1 . PRINT* statements don't write data directly to the disk; 
instead, the data is placed in the 256-byte output buffer. 
When this buffer is filled, the contents are automatically 
written to disk. (Closing the file will also write the buffer 
to disk.) 

2. If a DISK FULL ERROR occurs during execution of a PRINT* 
statement, you should realize that the current contents of the 
output buffer have not been written to the file. The data in 
the disk file is intact, but it doesn't contain the last few values 
you PRINTed to it. 

If your variables still contain the data, you can recover it 
directly. 
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Random Access Techniques 

Random access offers several advantages over sequential access: 

• Instead of having to start reading at the beginning of a file, 
you can read any record you specify. 

• To update a file, you don't have to read in the entire file, 
update the data, and write it out again. You can rewrite or 
add to any record you choose, without having to go through 
any of the other records. 

• Random access is more efficient - data takes up less space and 
is read and written faster. 

• Opening a file for random access allows you to write to and 
read from the file via the same buffer. 

• Random access provides many powerful statements and 
functions to structure your data. Once you have set up the 
structure, random input/output becomes quite simple. 

The last advantage listed above is also the "hard part" of random 
access. It takes a little extra thought. 

For the purposes of random access, you can think of a disk file as a 
set of boxes - like a wall of post-office boxes. Just like the post 
office receptacles, the file boxes are numbered. 

The number of boxes in a file will vary, but it's always a multiple 
of 5. 

The smallest non-empty file contains 5 boxes, numbered 1 through 
5. When the file needs more space to hold more data, TRSDOS 
provides it in increments of 5. 

These fixed-sized boxes are referred to as "records". Each record 
contains 256 bytes, 255 of which are available for storing your data. 

You can place data in any record, or read the contents of any 
record, with statements like: 

PUT i.. 5 write buffer- 1 contents to record 5 

GET 1.. 5 read the contents of record 5 into buffer- 1 



7-65 



DISK BASIC 




' 256 ^ 
^BYTES/ 

#6 



'256 \ 
,,BYTESy 

#1 



/256 \ 
VBYTESy 

#7 



/256 \ 
\BYTESJ 

#2' 



(256 ) 

Kbytes/ 

#8 



(256 \ 

Kbytes/ 

#3 



( 256 ^ 

VBYTES/ 

#9 



256 \ 
BYTES' 

m 



256 ^ 
BYTES/ 



#10 



BYTES 

till 




RECORDS IN DISK FILE 



I/O BUFFERS IN RAM 



The buffer is a waiting area for the data. Before writing data to a file, 
you must place it in the buffer assigned to the file. After reading 
data from a file, you must retrieve it from the buffer. 

As you can see from the sample PUT and GET statements above, data 
is passed to and from the disk in 256-byte chunks. 

"That's a lot of data." But most values occupy only a few bytes: 



Integers 

Single-precision numbers 
Double precision numbers 
Strings 



2 
4 
8 
Up to 255 



Therefore you'll want to place several values into the buffer before 
PUTting its contents into the disk file, to avoid wasting disk space. 

This is accomplished by 1 ) dividing the buffer up into fields and 
naming them, then 2) placing the string or numeric data into the 
fields. 

For example, suppose we want to store a glossary on disk. Each 
record will consist of a word followed by its definition. We start 
with: 

160 0PEN M R u , 1. "QLOSSfiRV/BflS" 

110 FIELD 1,15 AS WD$,240 AS MEfiNINQ$ 

Line 100 opens a file named GLOSSARY/BAS (creates it if it doesn't 
already exist); and gives buffer 1 random access to the file. 

Line 1 1 defines two fields onto buffer 1 : 

WD$ consists of the first 15 bytes of the buffer; 
MEANINGS consists of the last 240 bytes. 

WD$ and MEANINGS are now field-names. 
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What makes field names different? Most string variables point to an 
area in memory called the string space. This is where the value of 
the string is stored. 

Field names, on the other hand, point to the buffer area assigned 
in the FIELD statement. So, for example, the statement: 

16 PRINT WD* ": " MEANING* 
displays the contents of the two buffer fields defined above. 

These values are meaningless unless we first place data in the buffer. 
LSET, RSET and GET can all be used to accomplish this function. 
We'll start with LSET and RSET, which are used in preparation 
for disk output. 

Our first entry is the word "left-justify" followed by its definition. 

106 0PEN"RM, "GLOSSARY/BAS" 

110 FIELD 1, 15 AS WD*, 240 AS MEANING* 

120 LSET WD*="LEFT- JUSTIFY" 

130 LSET MEANING*="TQ PLACE A VALUE IN A FIELD FROM LEFT 

TO RIGHT; IF. THE DATA DOESN'T FILL THE FIELD, BLANKS ARE ADDED 

ON THE RIGHT; IF THE DATA IS TOO LONG, THE EXTRA CHARACTERS ON 

THE RIGHT ARE IGNORED. LSET IS A LEFT- JUSTIFY FUNCTION. " 

Line 1 20 left-justifies the value in quotes into the first field in buffer 
1. Line 130 does the same thing to its quoted string. When typing 
in line 130, you should insert line- feed <LF > characters (press the 
down arrow) to force line breaks as above. This makes it easier 
to print out the data after reading it back in to a string variable. 

Note: RSET would place filler-blanks to the left of the item. 
Truncation would still be on the right. 

Now that the data is in the buffer, we can write it to disk with a 
simple PUT statement: 

140 PUT 1,1 
150 CLOSE 

This writes the first record into the file GLOSSARY/BAS. 

To read and print the first record in GLOSSARY/BAS, use the 
following sequence: 

168 QPEN"R", 1, "GLOSSARY/BAS" 

170 FIELD 1, 15 AS WD*, 240 AS MEANING* 

180 GET 1,1 

190 PRINT WD* ": " MEANING* 

208 CLOSE 

Lines 160 and 170 are required only because we closed the file in 
line 1 50. If we hadn't closed it, we could go directly to line 1 80. 
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Random Access: A general procedure 

The above example shows the necessary sequences to read and 
write using random access. But it does not demonstrate the primary 
advantages of this form of access — in particular, it doesn't show 
how to update existing files by going directly to the desired record. 

The program below, GLOSSACC/BAS, develops the glossary example 
to show some of the techniques of random access for file maintenance. 
But before looking at the program, study this general procedure for 
creating and maintaining files via random access. 

Step Number See GLOSSACC/BAS, Line Number 

1. OPEN the file 110 

2. FIELD the buffer 120 

3. GET the record to be updated 140 

4. Display current contents of 145-170 
the record (use CVD,CVI,CVS 

before displaying numeric data) 

5. LSET and RSET new values into 210-230 
the fields (use MKD$,MKI$,MKS$ 

with numeric data before setting 
it into the buffer) 

6. PUT the updated record 240 

7. To update another record, continue 250-260 
at step 3. Otherwise, go to step 8. 

8. Close the file 270 
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1@ REM. . . GLOSSACC/BAS. . . 

i@0 CLS: CLEAR 300 

110 OPEN"R",l.. "GLOSSARV/BRS" 

120 FIELD 1,25 AS WD*, 228 AS MEANINGS 2 AS NX* 

138 INPUT "WHAT RECORD DO VOU WANT TO ACCESS"; RJi 

140 GET 1,R% 

145 NXfr=CVKNX*> 'SAVE LINK TO NEXT RLPHRBETICRL ENTRV 

150 PR I NT "WORD: "WD* 

160 PRINT"DEF-N:": PRINTMEANING* 

170 PR I NT "NEXT RLPHRBETICRL ENTRV: RECORD* "NX"/.: PRINT 

180 W*="": INPUT"TVPE NEW WORD<EN> OR <EN> IF OK"; W* 

190 D*="":PRINT n TVPE NEW DEF'N<EN> OR <EN> IF OK?" :LINEINPUTD* 

200 INPUT"TVPE NEW SEQUENCE NUMBER OR <EN> IF OK"; NX£ 

210 IF W*O u "THEN LSET WD*=W* 

220 IF D*0""THEN LSET MERNING*=D* 

230 LSET NX*=MKI*<NX*/.> 

240 PUT 1, r;^ 

245 R%=NX"/: "'USE NEXT ALPHA. LINK RS DEFAULT FOR NEXT RECORD 

250 CLS: INPUT" TVPE<EN> TO READ NEXT ALPHA. ENTRV, 

OR RECORD # <EN> FOR SPECIFIC ENTRV, 

OR O <EN> TO QUIT M ;RX 
260 IF 0<R5i THEN 140 
270 CLOSE 
280 END 

Notice we've added a field, NX$, to the record (line 120). NX$ will 
contain the number of the record which comes next in alphabetical 
sequence. This enables us to proceed alphabetically through the 
glossary, provided we know which record contains the entry which 
should come first. 

For example, suppose the glossary contains: 

pointer to next 
record* word (WD$) defn, alpha, entry (NX$) 

1 LEFT-JUSTIFY ~ 3 

2 BYTE ... 4 

3 RIGHT-JUSTIFY ... 

4 HEXADECIMAL ... 1 

When we read record 2 (BYTE), it tells us that record 4 
(HEXADECIMAL) is next, which then tells us record 1 (LEFT- 
JUSTIFY) is next, etc. The last entry, record 3 (RIGHT-JUSTIFY), 
points us to zero, which we take to mean "THE END". 

Since NX$ will contain an integer, we have to first convert that 
number to a two-byte string representation, using MKI$ (line 230 
above). 
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RwajossRcc/BflS" mma 




WHAT RECORD DO VOU WANT TO ACCESS? 4 ia«»;i 

WORD: HEX I DECIMAL 

DEF-'N: 

CAPABLE OF EXISTING IN ANV OF 16 STATES, E.G., THE HEXADECIMAL 

DIGITS 6, 1, 2, ..., S, A, B, C, D, E, F. HEXADECIMAL NUMBERS ARE STRINGS 

OF HEXADECIMAL DIGITS. 

NEXT ALPHABETICAL ENTRY: RECORD* 1 

TYPE NEW WORD<EN> OR <EN> IF OK? HEXftPEC IHRL HJHJd 
TYPE NEW DEF-"N<EN> OR <EN> IF OK? \£MM 

TYPE NEW SEQUENCE NUMBER OR <EN> IF OK? UMAil 




TYPE<EN> TO READ NEXT ALPHA. ENTRY, 

OR RECORD # <EN> F OR SPEC IFIC ENTRY, 

OR 8 <EN> TO QUIT? BZHID 
WORD: LEFT-JUSTIFY 
DEF-N: 

TO PLACE DATA IN A FIELD FROM LEFT TO RIGHT, ADDING BLANKS AS 
NECESSARY ON THE RIGHT TO FILL THE FIELD. ANY EXTRA CHARACTERS 
ON THE RIGHT ARE IGNORED. 

NEXT ALPHABETICAL ENTRY: RECORD* 3 

TYPE NEW WORD<EN> OR <EN> IF QK? HjUajl 
TYPE NEW DEF-N<EN> OR <EN> IF OK?HZSI3 

TYPE NEW SEQUENCE NUMBER OR <EN> IF OK? 2 QZEH3 
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The following program displays the glossary in alphabetical sequence: 

360 REM. . . GLOSSOLIT/BRS. . . 
216 CLS: CLEAR 300 

329 0PEN"R", 1, "GLOSSARY/BAS" 

330 FIELD 1,15 AS WD*. 238 flS MEANING*, 2 AS NX* 
348 INPUT"WHICH RECORD IS FIRST ALPHABET I CALLV "; HZ 
350 GET i,UZ 

368 PRINT rPRINTWD* 

370 PRINTMEANING* 

380 N2=CVI<NX*> 

390 INPUT"PRESS ENTER TO CONTINUE"; X 

400 IF NXO0 THEN 350 

410 CLOSE 

420 END 

Sub-Records 

In the glossary example, each entry required the full 255 bytes available 
in the buffer. Often this is not the case. When each information-unit 
fills only a part of the buffer, it is a good idea to define several 
identical sub-records on the buffer. That way you don't waste disk 
space by PUTting records which contain only a few bytes of useful 
information. 

For example, suppose we want to store a mailing list, and each entry 
will consist of: 

field field length 



name 1 8 

address 25 

city 14 

state 2 

last purchase amt. 4 

Total length of entry: 63 

Note: The last-purchase- amount will be a single-precision number. 
Such values require 4 bytes, therefore the field length is 4. 

If we didn't care about wasting space on the disk, we could use the 
following statement: 

FIELD 1, 18 AS NM*,25 AS AD*, 14 AS CTV*, 2 AS ST*, 4 AS LP* 

PUTting such a buffer would create a record consisting of 63 bytes of 
information followed by 255-63=192 unused bytes. 
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A more efficient approach fields the buffer into identical sub-records. 
In this case, we can create 255/63 = 4 sub-records plus only 3 wasted 
bytes at the end. 

Instead of using a very long FIELD statement to explicitly assign each 
field, we re-field the buffer once for each sub-record, using a dummy 
string, STARTHERE$, to start each sub-record at the appropriate 
position in the buffer. 

FORI3i=0 TO 3 

FIELD 1, <I5i*63> RS STflRTHERE*, 18 AS NM*<IJO, 

25 RS RD*<I5J>,14 Hb CTV$<IX),2 AS ST$<I%>,4 AS LP*<I5i> 

NEXT 

The first time through the loop, STARTHERES will have a length of 
zero. Therefore NM$(0) will start at the first byte; AD$(0), at the 
19th byte, etc.; LP$(0) will end at the 63rd byte. 

The second time through the loop, STARTHERES will have a length 
of 63. Therefore NM$(1) will start at the 64th byte; AD$(1), at the 
92nd byte, etc.; LPS(l) will end at the 126th byte. 

And so forth, until the buffer is completely defined. 

To place values in the subrecords of the buffer: assume our mailing 
list entries are stored in four arrays, N$( ),A$( ),C$( ),S$( ),LP( ). 

Then we can fill the buffer with four entries as follows: 

FOR IX=9T03 

LSET NM*<I5i)=N$<IJi> 

LSET flD*<IK)=fl*<IX) 

LSET CT$<IX>=C*<I?i) 

LSET ST*<IJi)=S*<I?i) 

LSET LP*<I5S>=MKS*<LP<I!0> 
NEXT 
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How to Access Sub-Records 

Since each record in such a file will contain four sub-records, we 
need a way to pull out the sub-record we want. This requires that 
each sub-record have a unique number which can be related to the 
record which contains it. 

For this example, suppose we have a printout of the entire mailing 
list, starting from the first sub-record in record 1 and going through 
to the last sub-record in the last record. We then number them 
sequentially, starting with 1. 

The following formulas use this number (we'll call it a key-number) 
to determine exactly where the sub-record is in the file: 

If the sub-record's key-number is KEY%, then 

PR% = INT((KEY%-l)/4)+l 
where PR% is the physical record that contains the sub-record, and 

SR%= KEY% - 4*(PR%-D 

where SR% is the sub-record number inside the physical record. For 
example, suppose we want to access the entry with key number =37 
(i.e., the 37th entry). Then the physical record which contains it is: 

INT((37-l)/4)+l == > record 10 

And its position in record 10 is: 

37 _ 4*(10-1)V== > sub-record number 1 
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A full working program for creating and manipulating a mailing list 
follows: 

106 CLEAR 1600 

110 OPEN"RM, "MAIL/BAS" 

120 CLS: INPUT "TYPE 1<EN> TO WRITE, 2<EN> TO READ, 

0<EN> TO QUIT"; NX 
130 IF HX=0 THEN CLOSE: END 
140 INPUT"TVPE KEY NUMBER<EN> OR 0<EN>"; KEYJi 
50 IF KEY%=0 THEN 120 
60 PRK=INT<<KEY%~l)/4)+l 
70 SR5i=KEYX-4*<PR5i-l) 
.80 FIELD 1, <<SRJi-l>*63) AS STflRTHERE$, IS AS NM*, 25 ftS AD$, 

14 AS CTV$,2 RS ST*, 4 AS LP$ 
190 GET l,PRJi 

00 IF NJi=2THEN300 
210 PRINT"WRITINQ SUBRECORD #"SR%"IN PHYSICAL RECORD #"PRJi 
*20 PRINT: PRINT"NflME? ,, TflB<20>; : LINE INPUT N$: LSET NM$=N$ 
230 PRINT"flDDRESS?"TAB(20>; : LINE INPUT At-: LSET flD*=fi* 
240 PRINT"CITY? !, TAB(20); : LINE INPUT C$: LSET CTY$=C$ 
250 PRINT"STATE?"TAB<20>.; : LINE INPUT S*: LSET ST$=S$ 
260 PRINT "LAST PURCHASE "TAB< 2©).; : I NPUTLP : t=SEKS*<tP> --' \ . '" - - 
270 PUT 1,PR5J: PRINT: INPUT "PRESS <EN> TO GO ON M ;X: GOTO 120 
1:00 PR I NT "READING SUBRECORD #"SR'i"IN PHYSICAL RECORD #"PR3J 
310 PRINT: PRINT"NflME"TRB<20>NM* 
320 PRINT H ADDRESS"TAB<20)AD$ 
330 PRINT"CITY"TAB<20>CTY$ 
340 PRINT"STATE"TAB<20)STf- 

350 PRINT USINC'LAST PURCHASE *####. ##".; CVS<LP*> 

360 PRINT: INPUT "PRESS <EN> TO GO 0N";X: GOTO120 



This program actually doesn't require you to fill the buffer with four 
meaningful sub-records. As soon as you've placed a sub-record in the 
correct position in the field, the entire buffer is written to disk. 
However, the extra space is not wasted; it is always available for 
subsequent sub-records to be added. 

Note that this would not be the most efficient way to create a list at 
one "sitting". In such a case you'd probably want to fill the buffer 
with four sub-records before doing the disk-write. The above program 
does, however, show you how to update a file using random access. 
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"MRtLflCC/BB5 M QMUl 





TVPE 1<EN> TO WRITE, 2<EN> TO READ, 

6<EN> TO QUIT? 1 SZEIII3 
TVPE KEV NUMBER<EN> OR 8<EN>? 3 13MM 
WRITING SUBRECORD # 3 IN PHYSICAL RECORD # 1 



NAME? 

ADDRESS? 

CITV? 

STATE? 

LAST PURCHASE 



S>yN«A& I.C. H2HHS 

2222 SECOND STREET ffiOHl 

OLD PORT B ZEIl 

? i2. si riMUi 



PRESS <EN> TO GO ON? HMM 



TVPE 1<EN> TO WRITE, 2<EN> TO READ, 

0<EN> TO QUIT? 2 ■*«■*;! 

TVPE KEV NUMBER<EN> OR 6<EN>? 1 Qffllil 
READING SUBRECORD # 1 IN PHYSICAL RECORD # 1 



NAME 

ADDRESS 

CITV 

STATE 

LAST PURCHASE 



JOHNSON, J. R. 

1624 RAM DRIVE 

FORT WUMPUS 

TX 

$ 188. 75 



PRESS <EN> TO GO ON? HHB3 




TVPE 1<EN> TO WRITE, 2<EN> TO READ, 

8<EN> TO QUIT? B H2BH 
READV 
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Overlapping Fields 



Suppose you want to access a field in two ways — in total and in 
part. Then you can assign two field names to the same area of the 
buffer. 

For example, if the first two digits of a six-digit stock-number specify 
a category, you might use the following field structure: 

FIELD 1,6 AS STOCKS, 

FIELD 1,2 ASCTGS, 



Now STOCKS will reference the entire stock-number field, while 
CTGS will reference only the first two digits of the number. 
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DISK BASIC Error Messages 



Code 



Message 



50 FIELD OVERFLOW 



Explanation 



More than 255 bytes were 
allocated to a random-access 
buffer. 



51 INTERNAL ERROR 



52 BAD FILE NUMBER 



53 FILE NOT FOUND 



54 BAD FILE MODE 



57 DISK I/O ERROR 



61 DISK FULL 



Error in disk operating system 
itself, or disk I/O fault. 

A file-buffer number was used 
improperly; number has not 
been assigned to a file with an 
OPEN statement. 

Attempt to read from a file 
which is not contained on the 
disk; check name/extension 
to see they were specified 
correctly. 

Attempt to perform disk 
file input or output which 
conflicts with the mode in 
which the file was opened. 

An error occurred during 
data transfer between the 
Computer and a disk file. 

All available space on the 
diskette has been used. 



62 INPUT PAST END 



During sequential input to a 
variable, the end of file was 
reached before any data 
characters were read. 



63 BAD RECORD NUMBER 



64 BAD FILENAME 



Record number in a PUT 
statement exceeded the 
range<l,340>. 

An invalid file specification 
was provided; study "File 
Specification", TRSDOS 
Overview. 



Note: Disk errors cannot be simulated via the ERROR statement 
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Code 



Message 



Explanation 



66 DIRECT STATEMENT IN FILE Attempt to LOAD, RUN, or 

MERGE a disk file which is 
not a BASIC program. 

Attempt to place more than 
48 files on a single diskette. 

Attempt to write to disk 
with write-protect notch 
covered. 

Attempt to access existing 
file with incorrect password. 



67 TOO MANY FILES 

68 DISK WRITE-PROTECTED 



69 



FILE ACCESS DENIED 
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Glossary 

access 

The method in which information is read from or written to disk; 
see random access and sequential access. 

address 

A location in memory, usually specified as a two-byte hexadecimal 
number. The address range <0 to FFFF>is represented in decimal 
as<0 to 32767 > <-32768, . . . , -1 > 

alphabetic 

Referring strictly to the letters A-Z. 

alphanumeric 

Referring to the set of letters A-Z and the numerals 0-9. 

argument 

The string or numeric quantity which is supplied to a function and 
is then operated on to derive a result; this result is referred to as 
the value of the function. 

array 

An organized set of elements which can be referenced in total or 
individually, using the array name and one or more subscripts. 
In BASIC, any variable name can be used to name an array; and 
arrays can have one or more dimensions. AR( ) signifies a 
one-dimensional array named AR; AR( , ) signifies a 
two-dimensional array named AR; etc. 

ASCII 

American Standard Code for Information Interchange. This method 
of coding is used to store textual data. Numeric data is typically 
stored in a more compressed format. 

ASCII format disk file 

Disk files in which each byte corresponds to one character of the 
original data. For example, a BASIC program stored in ASCII format 
"looks like" the program listing, except that each character is 
ASCII-coded. Compare to compressed-format file. 

background task 

A relatively slow routine which the computer executes along with 
other background tasks, and which is subject to interrupts. When 
the interrupt-driven tasks are completed, the background task 
continues. See foreground task, task. 
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backup disk 

An exact copy of the original: a "safe copy". You should keep 
backups of your original TRSDOS diskette and all important data 
diskettes. 

BASIC 

Beginners' All-purpose Symbolic Instruction Code, the programming 
language which is stored in ROM in the TRS-80. Radio Shack 
supports LEVEL I BASIC, LEVEL II BASIC, and DISK BASIC. 
LEVEL II is a subset of DISK BASIC. 



baud 

Signalling speed in bits per second. The LEVEL II cassette interface 
operates at 500 baud. 

binary 

Having two possible states, e.g., the binary digits and 1. The 
binary (base 2) numbering system uses sequences of zeroes and ones 
to represent quantities. This is analagous to the Computer's internal 
representation of date, using electrical values for and 1 . 

bit 

Binary digit; the smallest unit of memory in the Computer, capable 
of representing the values and 1 . 

bootstrap program 

A fundamental or primitive program which takes the Computer from 
an OFF condition to one in which it is capable of loading and 
executing a higher-level program — i.e., a program which allows the 
Computer to pull itself up "by its own bootstraps". A program 
which initializes the Computer. 

break 

To interrupt execution of a program. In BASIC the statement 

STOP 
causes a break in execution, as does pressing the BREAK key. 

buffer 

An area in RAM where data is accumulated for further processing. 
For example, to pass data from BASIC to a disk file, and vice- 
versa, the data must go through a file-buffer. 

buffer field 

A portion of the buffer which you define as the storage area for a 
buffer-field variable. Dividing a buffer into fields allows you to 
pass multiple values to and from disk storage. 
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byte 

The smallest addressable unit of memory in the Computer, 
consisting of 8 consecutive bits, and capable of representing 256 
different values, e.g., decimal values from to 255. 

compressed-format 

A method of storing information in less space than a standard ASCII 
representation would require. An integer always requires two bytes; 
a single-precision number, four; a double-precision number, 8 — 
regardless of how many characters are required to represent the 
numbers as text. String values cannot be stored in compressed 
format. 

BASIC programs in RAM and non- ASCII disk files are stored in 
compressed-format, with all BASIC keywords stored as special 
one-byte codes. 

command file 

A TRSDOS disk file with the extension /CUD. Such a file should 
consist of an executable Z-80 program, since TRSDOS will load and 
attempt to execute it when you type: 
filename HUUi] 

Command files can be placed on any disk; in effect, they extend 
the set of TRSDOS library commands (though, of course, they 
remain external to the TRSDOS system files). 

close 

Terminate access to a disk file. Before re-accessing the file, you 
must re-open it. 

data 

Information that is passed to our output from a program; under 
LEVEL II and DISK BASIC, there are four types of data: 

• integer numbers 

• single-precision floating point numbers 

• double-precision floating point numbers 

• character-string sequences, or just "strings" 

data/device control block (DCB) 

An area in RAM associated with an I/O buffer, containing 
information the Operating System requires in order to access the 
I/O device or file. 

debug 

To isolate and remove logical or syntax errors from a program. 
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decimal 

Capable of assuming one of ten states, e.g., the decimal digits 
0,1, ... ,9. Decimal (base 10) numbering is the everyday system, 
using sequences of decimal digits. Decimal numbers are stored in 
binary code in the Computer. 

default 

An action or value which is supplied by the Computer when you 
do not specify an action or value to be used. 

delimiter 

A character which marks the beginning or end of a data item, and 
is not a part of the data. For example, the double-quote symbol is 
a string delimiter to BASIC. 

destination 

The device or address which receives the data during a data transfer 
operation. For example, during a BACKUP operation, the destination 
disk is the one onto which the source-disk is being copied. 

device 

A physical part of the computer system used for data I/O, e.g., 
keyboard, display, line printer, cassette, disk drive, voice synthesizer. 

directory 

A listing of the files which are contained on a disk. 

disk drive or Mini Disk drive 

The physical device which writes data onto diskettes and retrieves it. 

diskette or disk 

A magnetic recording medium for mass data storage. 

drive specification or drivespec 

An optional field in a TRSDOS file specification and in some 
TRSDOS commands, consisting of a colon followed by one of the 
digits through 3. The drivespec is used to specify which drive is to 
be used for a disk read or write. 

When the drivespec is omitted from a command involving a read 
operation, TRSDOS will search, through all the disks for the 
desired file, starting with drive 0. 

When the drivespec is omitted from a command involving a write 
operation, TRSDOS will generally search through all non 
write-protected drives for the desired file. 
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drive number 

An integer value from to 3, specifying one of the Mini Disk 
drives. Drive is closest to the Expansion Interface, and Drive 3 
is farthest away. Drive must always contain the TRSDOS 
diskette, with a couple of exceptions. 

dummy variable 

A variable name which is used in an expression to meet syntactic 
requirements, but whose value is insignificant to the programmer. 

edit 

To change existing information. 

end of file or EOF 

A marker which indicates the end of a disk file, i.e., where the 
meaningful data ends and the unknown begins. 

entry point 

The address of a machine-language program or routine where 
execution is to begin. This is not necessarily the same as the 
starting address. Entry point is also referred to as the 
transfer address. 

expression 

A meaningful sequence of one or more variables, constants, 
operators and functions. 

field 

A user-defined subdivision of a random access file-buffer, created 
and named with the FIELD statement. 

field name 

A string variable which has been assigned to a field in a random 
access file-buffer via the FIELD statement. 

file 

An organized collection of related data. Under TRSDOS, a file is the 
largest block of information which can be addressed with a single 
command. BASIC programs and data sets are stored on disk in 
distinct files. 

file extension 

An optional field in a file specification, consisting of a / followed by 
one alphabetic and up to two alphanumeric characters; the 
extension can be used to identify the file type, e.g., /BAS, /TXT, 
/CIM, for BASIC, text, and core image, respectively. 
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filename 

A required field in a file specification, consisting of one alphabetic 
followed by up to 7 alphanumeric characters. Filenames are assigned 
when a file is created or renamed. 

file specification or filespec 

A sequence of characters which specifies a particular disk file under 
TRSDOS, consisting of a mandatory filename, followed by an 
optional extension, password, and drivespec. 

foreground task 

A relatively fast routine which the Computer must execute 
periodically, in sequence with other foreground tasks. Such 
tasks are interrupt-driven. See background task, task, interrupt. 

format 

To organize a new or magnetically erased diskette into tracks and 
sectors, via the TRSDOS FORMAT utility. BACKUP also implicitly 
formats a blank diskette. Formatted diskettes contain 35 tracks, 
each of which contains 10 sectors. 

granule 

The smallest unit of allocatable space on a disk, consisting of 
5 sectors. 

hexadecimal or hex 

Capable of existing in one of 16 possible states. For example, the 
hexadecimal digits are 0,1 ,2, . . , ,9,A,B,C,D,E,F. Hexadecimal 
(base- 16) numbers are sequences of hexadecimal digits. Address and 
byte values are frequently given in hexadecimal form. Under DISK 
BASIC, hexadecimal constants can be entered by prefixing the 
constant with &H. 

increment 

The value which is added to a counter each time one cycle of a 
repetitive procedure is completed. 

input 

To transfer data from outside the Computer (from a disk file, 
keyboard, etc.) into RAM. 
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interrupt 

A signal which causes the Computer to interrupt whatever it is doing 
and perform some other specified task; when the task is completed, 
the Computer will generally resume execution of the previous task. 
The TRS-80 Expansion Interface includes a 25 millisecond 
"heartbeat" interrupt, which is used to drive the real-time clock and 
other foreground tasks. Interrupt-driven tasks can be scheduled and 
assigned priorities, so that the Computer appears to be doing two 
or more things "at once". 

kilobyte or K 

1024 bytes of memory. Thus a 12 K ROM includes 12*1024=12288 
bytes. 

library commands 

A set of overlayed TRSDOS commands which are overlayed as 
needed into RAM between 5200 and 6FFF, to see which library 
commands are available, use the TRSDOS LIB command: 
LIB <EN> 

logical expression 

An expression which is evaluated as either True (=-1) or FALSE (=0). 

logical record 

A block of data which contains from 1 to 256 bytes, and can be 
addressed as a unit, regardless of whether the logical record is 
contained in a single record or spans two physical records. 

machine language 

The Z-80 instruction set, usually specified in hexadecimal code. All 
higher-level languages must be translated into machine-language in 
order to be executed by the Computer. 

null string 

A string which has a length of zero; For example, the assignment 

A$ = " " 
makes A$ a null-string. 

object code 

Machine language derived from "source code", typically, from 
Assembly Language. 
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octal 

Capable of existing in one of 8 states, for example, the octal digits 
are 0,1, ... ,7. Octal (base-8) numbers are sequences of octal 
digits. Address and byte values are frequently given in octal form. 
Under DISK BASIC, an octal constant can be entered by prefixing 
the octal number with the symbol &0. 

open 

To prepare a file for access by assigning a sequential input, 
sequential output, or random I/O buffer to it. 

output 

To transfer data from inside a Computer's memory to some external 
area, e.g., a disk file or a line printer. 

overlay 

To replace one block of code in RAM with another block. Also, the 
code which replaces the previous contents of RAM. For example, 
the TRSDOS system routines are stored on disk and loaded into a 
common area of RAM as overlays. 

parameter 

Optional information supplied with a command to specify how the 
command is to operate. TRSDOS parameters are placed inside 
parentheses. 

password 

An optional field in a filespec consisting of one alphanumeric 
followed by up to 7 additional alphanumeric characters. If a file 
is created without a password, 8 blanks become the default 
password. To access a file, you must specify the password in the 
filespec. 

Using the TRSDOS ATTRIB command, you can assign both update 
and access passwords; the access password will grant only a 
limited degree of access, while the update password grants total 
access to the file. See filespec. 

physical record 

The smallest amount of data which can be written to a disk file or 
read from it; under TRSDOS, physical records consist of 256 bytes. 
Note that physical record length can be ignored by the assembly- 
language programmer, since TRSDOS supports logical records of 
from 1 to 256 bytes in length. 
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prompt 

A character or message provided by the Computer to indicate that 
it's ready to accept keyboard input. 

protected file 

A disk file which has a non-blank password, and therefore can only 
be accessed by reference to that password. 

protection level 

The degree of access granted by using the access password: kill, 
rename, write, read, or execute. 

random access memory or RAM 

Semiconductor memory which can be addressed directly and either 
read from or written to. "User RAM" is that portion of RAM which 
is left untouched by TRSDOS and DISK BASIC code, from hex 7000 
to end of memory. 

real-time clock 

An interrupt driven routine that keeps time by updating certain 
memory locations every 25 milliseconds, regardless of what the 
current background task is. At power-on, the real-time clock is set 
to 00:00:00. When interrupts are disabled, the clock is stopped. 

reset 

To press the reset button on the rear left of the TRS-80, next to the 
Expansion Interface connection. Pressing reset is equivalent to 
powering up the Computer, except that the contents of user RAM 
are unaffected. 

resident system program 

That part of TRSDOS which remains in RAM; the "executive 
TRSDOS program", which calls in other TRSDOS code as needed. 

read-only memory or ROM 

Pre-programmed semiconductor memory which is directly 
addressable but can only be read, not written to. The LEVEL II 
TRS-80 includes 12K of ROM, where a bootstrap program, 
LEVEL II BASIC, and other code are permanently stored. 

routine 

A sequence of instructions to carry out a certain function; typically, 
a routine may be called from multiple points in a program. For 
example: keyboard scan routine. 
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sector 

One-tenth of a track on a diskette, containing 256 bytes of storage; 
a TRSDOS "physical record". 

sequential access 

Reading from a disk file or writing to it "from start to finish", 
without being able to directly access a particular record in the file. 

statement 

A complete instruction in BASIC. 

string 

Any sequence of characters which must be examined verbatim for 
meaning: in other words, the string does not correspond to a 
quantity. For example, the number 1234 represents the same 
quantity as 1000+234, but the string "1234" does not. (String 
addition is actually concatenation, or stringing-together, so that: 
"1234" equals "1" + "2" + "3" + "4"). 

system file 

A TRSDOS disk file with the extension /SYS. Such files are 
read-protected. To avoid confusion, don't use the extension /SYS 
on your own disk files. 

syntax 

The "grammatical" requirements for a command or statement. 
Syntax generally refers to punctuation and ordering of elements 
within a statement. See "Notation Conventions", General 
Information, for a description of syntax abbreviations used in 
this manual. 

task 

A relatively fundamental routine which the Computer performs 
periodically or upon request. 

track 

One of 35 concentric circles on the disk, each of which contains 
10 sectors, or 2560 bytes of storage. The tracks are not physical 
entities like grooves on a record; they are magnetic traces. 

transfer address 
See entry point. 

TRSDOS 

TRS-80 Disk Operating System, pronounced "triss-doss". 
TRSDOS is supplied on disk and is then loaded into RAM. 
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user RAM or user memory 
See random access memory. 

utility 

A program or routine which serves a limited, specific purpose. 
There are two extended TRSDOS utilities, FORMAT and BACKUP, 
and two non-TRSDOS utilities, DISKDUMP/BAS and TAPEDISK. ' 

write-protect 

To physically protect a disk from being written to by placing a tape 
over the write-protect notch. 
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'ONBOARD" ^ 
MEMORY <C 



L_ 



EXPANSION <S 
INTERFACE ^ 



X'0000 1 


1 K ROM 


X'0400 






11 K ROM 


X'3000 






I/O 


X'4000 


> 




X'4200 






X'5200 


16K 


RAM 


X'7000 




t 


X'8000 






16 K RAM 


X'COOO 






16 K RAM 


X'FFFF 





I/O DRIVERS AND BOOTSTRAP 



LEVEL II BASIC/DISK BASIC 



MEMORY MAPPED I/O 

BASIC VECTORS 
TRSDOS 

DISK BASIC 
TRSDOS UTILITIES 
USER MEMORY 

GENERAL PURPOSE 
USER MEMORY 



AUXILIARY USER MEMORY 



AUXILIARY USER MEMORY 
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TRSDOS Character Tables 



Bit-Pattern Codes 

The following table illustrates the bit pattern for each of the 128 
TRSDOS characters. The remaining 128 codes represent special 
graphics and space compression characters, as described later. 
See Notes. 

To use the table: Combine the most significant and least significant 
bit-patterns for a given character. For example, the character Q 
is represented by the pattern: 1010001 (decimal 81). 



MOST SIGNIFICANT BITS 
(b ? -b 5 ) 





0000 


LEAST 


0001 


SIGNIF. 


0010 


BITS 


0011 


(t^-b.,) 


0100 




0101 




0110 




0111 




1000 




1001 




1010 




1011 




1100 




1101 




1110 




1111 



000 


001 


010 


011 


100 


101 


110 


111 


NULL 


DLE 


SP 





@ 


P 


@ 


P 


BREAK 


DC1 


! 


1 


A 


Q 


a 


q 


STX 


DC2 


" 


2 


B 


R 


b 


r 


ETX 


DC3 


# 


3 


C 


S 


c 


s 


EOT 


DC4 


$ 


4 


D 


T 


d 


t 


ENQ 


NAK 


% 


5 


E 


U 


e 


u 


ACK 


SYN 


& 


6 


F 


V 


f 


V 


BEL 


ETB 


' 


7 


G 


w 


9 


w 


BKSP 


CAN 


( 


8 


H 


X 


h 


X 


HT 


EM 


) 


9 


I 


Y 


i 


V 


LF 


SUB 


* 




J 


Z 


J 


z 


VT 


ESC 


+ 


; 


K 


T 


k 


1 


FF 


HOME 


• 


< 


L 


* 


I 


f 


CR 


BOL 


- 


= 


M 


+ 


m 


-*- 


CURON 


EREOL 


• 


> 


N 


+ 


n 


-► 


CUROFF 


EREOF 


/ 


? 


O 




o 


DEL 
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Dec. Hex. 



Char. 



Code 
Dec. Hex. 



Char. 
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Code 
Dec. Hex. 



Note: 96-127 (hex 60-7F) are lower-case counterparts to 64-95 (hex 40-5F).; only 
upper-case characters are displayable. 



Char. 






00 


NULL 


32 


20 


SPACE 


64 


40 


@ 


1 


01 


BREAK 


33 


21 


! 


65 


41 


A 


2 


02 


STX 


34 


22 


" 


66 


42 


B 


3 


03 


ETX 


35 


23 


# 


67 


43 


C 


4 


04 


EOT 


36 


24 


$ 


68 


44 


D 


5 


05 


ENQ 


37 


25 


% 


69 


45 


E 


6 


06 


ACK 


38 


26 


& 


70 


46 


F 


7 


07 


BEL 


39 


27 


' 


71 


47 


G 


8 


08 


BKSP 


40 


28 


( 


72 


48 


H 


9 


09 


HT 


41 


29 


) 


73 


49 


I 


10 


0A 


LF 


42 


2A 


* 


74 


4A 


J 


11 


0B 


VT 


43 


2B 


+ 


75 


4B 


K 


12 


OC 


FF 


44 


2C 


' 


76 


4C 


L 


13 


0D 


CR 


45 


2D 


_ 


77 


4D 


M 


14 


0E 


CURON 


46 


2E 


. 


78 


4E 


N 


15 


OF 


CUROFF 


47 


2F 


/ 


79 


4F 





16 


10 


DLE 


48 


30 





80 


50 


P 


17 


11 


DC1 


49 


31 


1 


81 


51 


Q 


18 


12 


DC2 


50 


32 


2 


82 


52 


R 


19 


13 


DC3 


51 


33 


3 


83 


53 


S 


20 


14 


DC4 


52 


34 


4 


84 


54 


T 


21 


15 


NAK 


53 


35 


5 


85 


55 


U 


22 


16 


SYN 


54 


36 


6 


86 


56 


V 


23 


17 


ETB 


55 


37 


7 


87 


57 


w 


24 


18 


CAN 


56 


38 


8 


88 


58 


X 


25 


19 


EM 


57 


39 


9 


89 


59 


Y 


26 


1A 


SUB 


58 


3A 




90 


5A 


Z 


27 


1B 


ESC 


59 


3B 


; 


91 


5B 


* 


28 


1C 


HOME 


60 


3C 


< 


92 


5C 


t 


29 


1D 


BOL 


61 


3D 


= 


93 


5D 




30 


1E 


EREOL 


62 


3E 


> 


94 


5E 


-► 


31 


1F 


EREOF | 


63 


3F 


? 


95 


5F 


i 
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Notes 

The TRSDOS character set may be subdivided into the following 
functional groups: 

decimal code hex code function 



0-31 00- IF Control characters 

32-95 20-5F Keyboard/display characters 

96-127 60-7F Non-printing characters (code-32 is printed) 

128-191 80-BF Graphics characters 

192-255 CO-FF Space-compression codes 



The following control characters may be entered directly from the 
keyboard: 



character 



BREAK 

BKSP 

HT 

CR 

CAN 

EM 

SUB 

ESC 

EREOF 

SP 



BREAK 



t 
ENTER 
SHIFT -*- 
SHIFT -► 
SHIFT t 
SHIFT 4 
CLEAR 
SPACE-BAR 



8-16 



Appendices 



For a description of the graphics characters, run the following 
program. If you do not have a line printer connected, change 
all LPRINTs to PRINTs and use the shift-® key to pause the 
display. 

10 CLS: DEFINT fl-Z 

28 FOR I =128 TO 191 

30 POKE 15360, I 

35 LPRINT CHR*<138> 

40 LPRINT"GRRPHICS CODE # ".; I 

45 LPRINT CHR$<138) 

50 R1=P0 1 NT < 0, > : R2=P0 1 NT ( i, > 

60 R3=P0 1 NT ( 0, 1 ) : R4=P0 I NT < 1, 1 > 

70 A5=PQ I NT < 0, 2 ) : R6=P0 I NT < 1, 2 > 

80 LPR I NTTRB < 8 ) CHR* < Hi* ( -40 ) +48 ) i CHR* < R2* ( -40 ) +48 ) 

90 LPR I NTTRB < 8 > CHR* < A3* < -40 ) +48 ) ; CHR* ( R4* < -40 ) +48 ) 

100 L PR 1 NTTRB ( 8 ) CHR* < fl5* < - 40 ) +48 ) i CHR* < A6+- < -40 > +48 ) 

110 NEXT 

The space-compression codes provide a compact means of 
representing strings of blanks from zero to 63 blanks. 
For example, CO represents zero blanks; CI, 1 blank; C2, 
2 blanks; FF, 63 blanks. 
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Base Conversions 

The following table lists base conversions for all one-byte values. 



DEC. 



BINARY 



HEX. OCT. 



DEC. 6INRR.Y 



HEX. OCT. 



8 
1 
2 


(kCiCkCiCiClCiCi 


00 
01 
02 


KkpO 

001 

082 


43 
44 
45 


80181811 


2B 


053 




V" w J- %»* •*• V «*• «*■> 

00101100 


2C 


054 


©l30trt3ti«3.L 

00888818 


00101101 


2D 


055 


3 
4 


WMMftCsbi-l -1 


03 
04 


883 
884 


46 
47 


08101110 


2E 


056 


88800100 


00101111 


2F 


057 


5 


00008101 


85 


885 


48 


00118888 


38 


060 


6 


08888118 


86 


006 


49 


88118881 


31 


061 


7 


88888111 


87 


007 


50 


80118818 


32 


062 


8 


88881888 


08 


010 


51 


00110011 


33 


063 


9 


88881881 


09 


011 


52 


00110100 


34 


064 


10 


88881818 


0fl 


012 


53 


00110101 


35 


065 


11 


88881811 


0B 


813 


54 


88118118 


36 


066 


12 


88881100 


0C 


014 


55 


88118111 


37 


067 


13 


80001181 


0D 


815 


56 


88111888 


38 


070 


14 


88881118 


0E 


816 


57 


88111881 


39 


071 


15 


00001111 


OF 


817 


58 


88111818 


3fl 


072 


16 


00018008 


10 


828 


59 


88111811 


3B 


873 


17 


00818881 


11 


821 


68 


88111100 


3C 


074 


18 


88818818 


12 


022 


61 


00111101 


3D 


875 


13 


88818811 


13 


023 


62 


80111110 


3E 


876 


28 


80018188 


14 


824 


63 


80111111 


3F 


077 


21 


80010101 


15 


025 


64 


CM &&GtGiGi(k 


48 


100 


VXVKflOKJKfKf 


22 


00010110 


16 


826 


65 


01000001 


41 


101 


23 


80010111 


17 


827 


66 


81888818 


42 


102 


24 


80011080 


18 


838 


67 


81080811 


43 


103 


25 


80011001 


19 


831 


68 


81888188 


44 


104 


26 


00011010 


Ifi 


832 


69 


81888181 


45 


105 


27 


00011011 


IB 


833 


78 


81888118 


46 


106 


28 


00011100 


1C 


834 


71 


81880111 


47 


107 


29 


00011181 


ID 


835 


72 


01001000 


48 


110 


38 


88011110 


IE 


836 


73 


01001801 


49 


111 


31 


80011111 


IF 


037 


74 


81001010 


4fl 


112 


32 


00100008 


20 


040 


75 


01001011 


4B 


113 


33 


00100001 


21 


841 


76 


01001100 


4C 


114 


34 


00100010 


22 


842 


77 


01881181 


4D 


115 


35 


00100011 


23 


043 


78 


81881118 


4E 


116 


36 


00100100 


24 


844 


79 


81881111 


4F 


117 


37 


88180181 


25 


045 


88 


81818888 


50 


120 


38 


00100118 


26 


046 


81 


81818881 


51 


121 


39 


00100111 


27 


047 


82 


81818818 


52 


122 


48 


00101000 


28 


050 


83 


01818811 


53 


123 


41 


00101001 


29 


051 


84 


01818188 


54 


124 


42 


00101810 


2fi 


052 


85 


81818181 


55 


125 
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DEC. 



BINARY 



HEX. 



OCT. 



DEC. BINARY 



HE> 



OCT. 



86 


01010110 


56 


126 


8? 


01010111 


5? 


X& i 


88 


01011000 


58 


130 


89 


01011001 


59 


131 


90 


01011010 


5fl 


X«-C. 


91 


01011011 


5B 


133 


92 


01011100 


5C 


134 


93 


01011101 


5D 


135 


94 


01011110 


5E 


136 


95 


01011111 


5F 


13? 


96 


01100000 


60 


140 


9? 


01100001 


61 


141 


98 


01100010 


62 


142 


99 


01100011 


63 


143 


100 


01100100 


64 


144 


101 


01100101 


65 


145 


102 


01100110 


66 


146 


103 


01100111 


67 


147 


104 


01101000 


68 


15© 


105 


01101001 


69 


151 


106 


01101010 


6fi 


152 


10? 


01101011 


6B 


153 


108 


01101100 


6C 


154 


109 


01101101 


6D 


155 


110 


01101110 


6E 


156 


ill 


01101111 


6F 


157 


112 


01110000 


70 


160 


113 


01110001 


71 


161 


114 


01110010 


72 


162 


115 


01110011 


f S 


163 


116 


01110100 


74 


164 


117 


01110101 


75 


165 


118 


01110110 


76 


166 


119 


01110111 


{ (' 


167 


120 


01111000 


7y 


170 


121 


01111001 


79 


171 


122 


01111010 


?fl 


172 


123 


01111011 


?B 


173 


124 


01111100 


?C 


174 


125 


01111101 


?D 


175 


126 


01111110 


?E 


176 


12? 


01111111 


?F 


17? 


128 


10000000 


80 


200 


129 


10000001 


81 


201 


130 


10000010 


82 


202 


131 


10000011 


83 


203 


132 


10000100 


84 


204 


133 


10000101 


85 


285 



134 


10000110 


fc'fo 


206 


135 


10000111 


8? 


207 


136 


10001000 


88 


210 


137 


10001001 


89 


211 


138 


10001010 


8fl 


212 


139 


10001011 


8B 


213 


140 


10001100 


8C 


214 


141 


10001101 


8D 


215 


142 


10001110 


8E 


216 


143 


10001111 


8F 


217 


144 


10010000 


90 


220 


145 


10010001 


91 


221 


146 


10010010 


92 


222 


14? 


10010011 


93 


223 


148 


10010100 


94 


224 


149 


10010101 


95 


CC-J 


150 


10010110 


96 


226 


151 


10010111 


97 


£.£!*' 


152 


10011000 


98 


230 


153 


10011001 


99 


231 


154 


10011010 


9fl 


232 


155 


10011011 


9B 


233: 


156 


10011100 


9C 


234 


157 


10011101 


9D 


235 


158 


10011110 


9E 


236 


159 


10011111 


9F 


237 


160 


10100000 


fl0 


240 


161 


10100001 


fll 


241 


162 


10100010 


A2 


242 


163 


10100011 


A3 


243 


164 


10100100 


A4 


244 


165 


10100101 


A5 


245 


166 


10100110 


A6 


246 


16? 


10100111 


A7 


247 


168 


10101000 


AS 


250 


169 


10101001 


A9 


251 


170 


10101010 


AA 


252 


171 


10101011 


AB 


253 


172 


10101100 


AC 


254 


173 


10101101 


AD 


255 


174 


10101110 


AE 


256 


175 


10101111 


AF 


25? 


176 


10110000 


B0 


260 


1?? 


10110001 


Bl 


261 


178 


10110010 


B2 


262 


179 


10110011 


B3 


263 


180 


10110100 


B4 


264 


181 


10110101 


B5 


265 


182 


10110110 


B6 


266 
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DEC. 



BINARY 



HEX. 



OCT. 



DEC. 



BINARY 



HEX. 



OCT. 



183 


10110111 


B? 


26? 


219 


11011011 


DB 


":3": 


184 


10111000 


B8 


270 


220 


11011100 


DC 


334 


185 


10111001 


B9 


271 


221 


11011101 


DD 


335 


186 


10111010 


BA 


272 


222 


11011110 


DE 


33-6 


187 


10111011 


BB 


273 


tL£.S 


11011111 


DF 


""£*%"? 


188 


10111100 


BC 


274 


224 


11100000 


EO 


340 


189 


10111101 


BD 


275 


225 


11100001 


El 


341 


196 


10111110 


BE 


276 


226 


11100010 


E2 


342 


191 


10111111 


BF 


277 


227 


11100011 


E3 


343 


192 


11000000 


CO 


300 


228 


11100100 


E4 


344 


193 


11000001 


CI 


301 


229 


11100101 


E5 


345 


194 


11000010 


C2 


362 


236 


11100110 


E6 


346 


195 


11000011 


C3 


303 


231 


11100111 


E7 


34? 


196 


11006100 


C4 


304 


/-,—..-, 
i^i 


11101000 


E8 


350 


19? 


11000101 


C5 


305 


233 


11101001 


E9 


351 


198 


11000110 


C6 


306 


234 


11101010 


EA 


Ji-JC 


199 


11000111 


C7 


307 


235 


11101011 


EB 


353 


266 


11001000 


C8 


310 


236 
23? 


11101100 
11101101 


EC 
ED 


354 


201 


11001001 


C9 


311 


238 


11101110 


EE 


356 


202 


11001010 


CA 


312 


239 


11101111 


EF 


35? 


263 


11001011 


CB 


313 


240 


11110000 


F0 


360 


204 
205 


11001100 
11001101 


CC 
CD 


314 
315 


241 
242 


11110001 
11110010 


Fl 
F2 


361 
362 


206 


11001110 


CE 


316 


243 


11110011 


F3 


363 


20? 
208 
209 


11001111 
11010000 
11010001 


CF 
DO 
Dl 


317 
320 
321 


244 
245 
246 


11110100 
11110101 
11110110 


F4 
F5 
F6 


364 
365 
366 


210 
211 


11010010 
11010011 


D2 
D3 


322 
323 


24? 
248 


11110111 
11111000 


F7 
F8 


367 
370 


212 
213 
214 
215 


11010100 
11010101 
11010110 
11010111 


D4 
D5 
D6 
D7 


324 
325 
326 
327 


249 
250 
251 
252 


11111001 
11111010 
11111011 
11111100 


F9 
FA 
FB 
FC 


371 
372 

374 


216 


11011000 


D8 


330 


253 


11111101 


FD 


375 


21? 


11011001 


D9 


~""?i 


254 


11111110 


FE 


376 


218 


11011010 


DA 


332 


•-icir 


11111111 


FF 


377 
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Index 



Subject Page 

&H, BASIC hex constant prefix 7-6 

&0, BASIC octal constant prefix 7-6 

< EN>, carriage return character 7-38 

<LF>, line-feed character 7-38 

access, 8-2 

random 7-65,8-11 

sequential 7-60, 8-10 

address 8-2 

alphanumeric 8-2 

argument 8-2 

array 8-2 

-notation 1-4 

ASCII 8-2 

format 7-32, 8-2 

assembly -language 

I/0,TRSDOS 6-5 

access from BASIC 7-14, 7-20 

ATTRIB, TRSDOS command 4-12 

AUTO, TRSDOS command 4-11 

BACKUP, TRSDOS utility 

abbreviated instructions for 2-16 

detailed description of 5-2 

Important Notice 2-17 

background task 8-2 

backup disk 8-3 

Base Conversions, 

decimal/binary /octal/hex 8-18 

BASIC, TRSDOS 

command file 1-2, 3-4, 7-2 

BASIC2, TRSDOS command 4-2 

baud 8-3 

binary 8-3 

bit 8-3 

blocking of logical records 

under TRSDOS 6-3, 6-7 

bootstrap program 8-3 

break 8-3 

buffer 6-5,6-6, 7-2, 7-33 ff, 8-3 

byte 84 

cassette I/O under 

DISK BASIC 



.7-5,7-10 



Subject Page 

CLOCK, TRSDOS command 4-14 

clock, real time, see real-time clock 

CLOSE, BASIC statement 7-36 

close a file 6-11,7-36,8-4 

CMD"D", BASIC statement 7-7 

CMD"R", BASIC statement 7-10 

CMD"S", BASIC statement 7-10 

CMD-T", BASIC statement 7-10 

command 

file 3-7, 8-4 

format 3-5 

command, 

TRSDOS library 4-2 ff, 8-8 

TRSDOS system 4-1 1 ff 

compressed format, BASIC 7-31,8-4 

COPY, TRSDOS command 4-15 

CVD, BASIC function 7-54 

CVI, BASIC function 7-54 

CVS, BASIC function 7-54 

data 8-4 

data/device control block 

(DCB) 6-6, 8-4 

data diskette 5-4 

DATE, TRSDOS command 4-15 

DEBUG, TRSDOS command 4-3 

debug 8-4 

decimal 8-5 

default 8-5 

delimiter, 6-6, 8-5 

BASIC INPUT # 7-40 

DEFFN, BASIC statement 7-11 

DEFUSR, BASIC statement 7-14 

destination 8-5 

diskette 5-2 

DEVICE, TRSDOS command 4-16 

device 8-5 

DIR, TRSDOS command, 4-16 

directory 8-5 



Index 



Subject Page 

DISK BASIC 

error messages 7-77 

ROM calls 7-22 

versions and releases 1-6 

DISKDUMP/BAS, auxiliary 

utility program 5-8 ff 

diskette, 

data 2-10 

TRSDOS software 2-10 

diskette 2-5 ff, 8-5 

care 2-8 

organization 2-6, 6-2 

specifications 2-10 

drive number 8-6 

drive numbering 2-5 

drive specification 3-6, 3-8, 8-5 

drive zero 2-5 

dummy variable 8-6 

DUMP, TRSDOS command 4-18 

end of file 

(EOF) 4-16, 6-6, 6-9, 7-55, 8-6 

entry point 4-18, 5-6, 6-8, 7-14, 8-6 

EOF, BASIC function 7-55 

ERROR, BASIC statement 7-6 

error messages, 

BASIC 7-6, 7-77 

TRSDOS 6-12 

expression 8-6 

FIELD, BASIC statement 7-47 

field, 8-6 

overlapping 7-76 

field name 7-48, 7-67, 8-6 

file, TRSDOS 3-3, 6-3 ff, 8-6 

extension 3-6 ff, 7-32, 8-6 

name 3-6, 8-7 

specification 3-6 ff, 6-6, 8-7 

foreground task 3-2,4-9,4-10,8-7 

FORMAT, TRSDOS utility 54 ff 

format 54 ff, 8-7 

FREE, TRSDOS command 4-19 



Subject Page 

GET, BASIC statement 7-49 

granule 4-16,4-19,54,6-3,6-12,8-7 

hexadecimal 8-7 

constants, BASIC 7-6 

increment 8-7 

input 8-7 

INPUT #, BASIC statement 7-37 

INSTR, BASIC function 7-15 

interrupt 7-5, 7-10, 8-8 

KILL, BASIC command 7-28 

KILL, TRSDOS command 4-19 

kilobyte 8-8 

LIB, TRSDOS command 4-19 

library command, TRSDOS 4-11 

LINE INPUT, BASIC statement 7-16 

LINE INPUT #, BASIC statement 7-42 

LIST, TRSDOS command 4-20 

LOAD, BASIC command 7-28 

LOAD, TRSDOS command 4-20 

LOF, BASIC function 7-56 

LSET, BASIC statement 7-53 

machine language, 8-8 

dump to disk 4-18 

load from disk 4-20 

reserve RAM for 7-3 

access routines from 

BASIC 7-14,7-20 

Master Password 4-21, 5-2 

MERGE, BASIC command 7-29 

MID$=, BASIC statement 7-17 

Mini Disk 2-1 ff 

connection 2-3 

operation 2-5 

specifications 2-10 

MKD$, BASIC function 7-57 

MKI$, BASIC function 7-57 

MKS$, BASIC function 7-57 

Notation 1-3, 6-5 

null string 8-8 
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Subject Page 

object code 8-8 and see machine 

language 

octal 8-9 

constants, BASIC 7-6 

OPEN, BASIC statement 7-34 

open a file 6-6, 6-9, 7-33, 7-34, 8-9 

parameter 8-9 

password 3-6, 3-8, 4-12, 4-13, 8-9 

PRINT, TRSDOS command 4-21 

PRINT #, BASIC statement 7-43 

prompt 8-10 

PROT, TRSDOS command 4-21 

protected file 6-12, 8-10 

protection level 4-12, 4-22, 8-10 

PUT, BASIC statement 7-50 

random access 7-65 

random access memory (RAM) 8-10 

allocation 1-2, 3-4, 6-2 

random access memory (RAM), 

BASIC program storage in 7-32 

reserving for machine language code 

under DISK BASIC 7-3 

read only memory (ROM) 8-10 

calls from BASIC 7-22 

calls from TRSDOS 6-8 ff 

organization 6-2 

real-time clock, 

in Expansion Interface 1-2 

memory location of 4-9 

to display 4-14 

to set 4-23 

to turn off 7-10 

to turn on 7-10 

record, TRSDOS 

physical 6-4, 6-7, 8-9 

logical 6-7, 8-8 

release 1-6 

RENAME, TRSDOS command 4-22 

reset ; . . .8-10 

resident program 3-4, 8-10 

ROM (see read only memory) 



Subject Page 

RSET, BASIC statement 7-53 

RUN "program", BASIC command .... .7-31 

SAVE, BASIC command 7-31 

sector, diskette 2-6, 8-11 

sequential access 7-60, 8-11 

statement, BASIC 8-11 

string 8-11 

subrecord 7-71 

syntax, 8-11 

TRSDOS command 3-5 

system 

command 4-22 

file 3-7,8-11 

routine 6-5 ff 

TAPEDISK, auxiliary utility 5-6 

task, 

background 8-2 

foreground 3-2,4-9,4-10,4-14,8-7 

TIME, TRSDOS command 4-23 

TIMES, BASIC function 7-19 

TRACE, TRSDOS command 4-10 

transfer address 4-18, 8-11 

track, diskette 2-6, 8-11 

TRSDOS 

assembly I/O 6-5 ff 

error messages 6-12 

file specification 3-6 

library commands 4-11 

memory organization 6-2 

RAM allocation 3-4, 8-13 

system commands 4-2 

utilities 5-1 ff 

versions and releases 1-6 

USING, BASIC PRINT 

format modifier 7-46 

USR, BASIC function 7-20 

utility 

TRSDOS 5-2 

auxiliary 5-6 

VERIFY, TRSDOS command 4-24 

versions and releases 1-6 

write protect 2-6 
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IMPORTANT NOTICE 

ALL RADIO SHACK COMPUTER PROGRAMS ARE DISTRIBUTED ON AN 
"AS IS" BASIS WITHOUT WARRANTY 

Radio Shack shall have no liability or responsibility to customer or any other 
person or entity with respect to any liability, loss or damage caused or alleged to 
be caused directly or indirectly by computer equipment or programs sold by 
Radio Shack, including but not limited to any Interruption of service, loss of 
business or anticipatory profits or consequential damages resulting from the use 
or operation of such computer or computer programs. 

NOTE: Good data processing procedure dictates that the user test the program, 
run and test sample sets of data, and run the system in parallel with the 
system previously in use for a period of time adequate to Insure that 
results of operation of the computer or program are satisfactory. 
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LIMITED WARRANTY 



Radio Shack warrants for a period of 90 days from the date of delivery 
to customer that the computer hardware described herein shall be free 
from defects in material and workmanship under normal use and service. 
This warranty shall be void if this unit's case or cabinet is opened or if 
the unit is altered or modified. During this period, if a defect should 
occur, the product must be returned to a Radio Shack store or dealer 
for repair. Customer's sole and exclusive remedy in the event of defect 
is expressly limited to the correction of the defect by adjustment, re- 
pair or replacement at Radio Shack's election and sole expense, except 
there shall be no obligation to replace or repair items which by their 
nature are expendable. No representation or other affirmation of fact, 
including but not limited to statements regarding capacity, suitability 
for use, or performance of the equipment, shall be or be deemed to be a 
warranty or representation by Radio Shack, for any purpose, nor give 
rise to any liability or obligation of Radio Shack whatsoever. 

EXCEPT AS SPECIFICALLY PROVIDED IN THIS AGREEMENT, 
THERE ARE NO OTHER WARRANTIES, EXPRESS OR IMPLIED^ 
INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES 
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PUR- 
POSE AND IN NO EVENT SHALL RADIO SHACK BE LIABLE FOR 
LOSS OF PROFITS OR BENEFITS, INDIRECT, SPECIAL, CONSE- 
QUENTIAL OR OTHER SIMILAR DAMAGES ARISING OUT OF 
ANY BREACH OF THIS WARRANTY OR OTHERWISE. 
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